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[INTRODUCTION 


Mixed-language programming is the process of creating programs from 
two or more source languages. This capability allows you to combine the 
unique strengths of Microsofte BASIC, C, FORTRAN, Pascal, and Macro 
Assembler. Any one of these languages (in their recent versions) can call 
any of the others. Virtually all of the routines from all extensive language 
libraries are available to a mixed-language program. 


For example, mixed-language programming helps you effectively use as- 
sembly language. You can develop the majority of your program quickly 
with Microsoft C or QuickBASIC, then call assembly for those few routines 
that are executed many times and must run with utmost speed. 


Mixed-language programming also facilitates the transition from one lan- 
guage to another. You may have a large FORTRAN program which you 
are converting to C. You can replace your FORTRAN subroutines, one by 
one, with corresponding C functions. C-generated code can come on-line as 
soon as each function is written. 


Finally, mixed-language programming is particularly valuable if you are 
marketing your own libraries. With the techniques presented here, you can 
produce libraries for any of the languages mentioned above, often with 
little change. 


How to Use this Manual 


This manual focuses on the concepts, syntax, and programming methods 
necessary to write mixed-language programs. The manual assumes that 
you have a basic understanding of the languages you wish to combine and 
that you already know how to write, compile, and link multiple-module 
programs with these languages. The manual does not attempt to teach the 
basics of programming in any particular language. 


Mixed-language programming is not particularly difficult, but it does 
require that you understand certain basic issues. This manual first 
presents these issues in some detail. Once you understand the basics, you 
can proceed to the sections that are relevant to the languages you are 
using. 
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The manual is divided into two parts; each part has a different orientation 
and purpose: 


e Part 1. Mized-Language Interfaces. 


Part 1 shows how to establish an interface between any two 
languages (of those listed above). It does not assume you have any 
background in mixed-language programming, and extensively 1 uses 
examples with simple parameter lists. 


e Part 2. Data Handling Reference. 


Part 2 shows how to pass different kinds of data. This part of the 
manual assumes you already know the basics of mixed-language 
programming. It focuses on the particular programming considera- 
tions for passing strings, arrays, common blocks, etc. 


Depending on your current level of knowledge, you may not need to start 
reading this manual at the beginning. The manual is structured so that 
you can easily turn to the section that would be most helpful: 


1. 


For an introduction to mixed-language concepts, read Chapter 1, “Ele- 
ments of Mixed-Language Programming.” 


Depending on the high-level language of your main program, read 
either Chapter 2, 3, 4, or 5. The opening section of each of these 
chapters describes mixed-language syntax in detail. For quick refer- 
ence, turn directly to the section in Chapters 2-5 most relevant to 
your combination of languages. 


To find out about calls to assembly language, read Chapter 6, 
“Assembly-to-High-Level Interface.” 


After you have learned how to pass simple arguments ae as 
integers) between languages, use Part 2 as a reference for passing more 
complex kinds of data, such as strings and arrays. 


Definitions 


The notational conventions used in this manual are consistent with the 
conventions described in the user’s guide for each Microsoft language. 
However, the following terms are used in specialized ways: 


Term ___Definition _ 


Routine Any function, subprogram, subroutine, or procedure 


x11 


that can be called from another language. 


The concept is similar to that of a procedure in assem- 
bly language; however, the term “routine” 1s used in 
most contexts to avoid confusion with the Pascal key- 
word procedure. 


Parameter 


Interface 


Formal 
parameter 


A piece of data passed directly between two routines. 
(External data are shared by all routines, but cannot 
be said to be passed.) 


Although elsewhere the term “argument” is sometimes 
used interchangeably with “parameter,” in this 
manual, “argument” is used to refer to the particular 
values or expressions given for parameters. 


A method for providing effective communication 
between different formats. With high-level languages, 
an interface is often established by some kind of for- 
mal declaration. 


A formal parameter is a dummy parameter declared in 


an interface statement or declaration. C uses parame- 
ter type declarations rather than formal parameters. 
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Elements of Mixed-Language Programming 


Microsoft languages have special keywords that facilitate mixed-language 
programming (described in Chapters ae) However, in order to use these 
keywords, you first need to understand the basic issues involved. 


This chapter describes the elements of mixed-language programming: how 
languages differ and how to resolve these differences. If you understand the 
principles described in the next few paragraphs, then you may want to 
turn directly to other chapters in this manual. Nevertheless, you still may 
find it helpful to refer to this chapter occasionally. 


Section 1.1 presents the basic context of a mixed-language call, when and 
how you make such a call. 


Sections 1.2—1.4 present the three fundamental mixed-language program- 
ming requirements: 


e Naming convention requirement 
e Calling convention requirement 


e Parameter-passing requirement 


Section 1.5 presents the compile-time and link-time issues, including use of 
memory models. 


1.1 Making Mixed-Language Calls 


Mixed-language programming always involves a call; specifically, it in- 
volves a function, procedure, or subroutine call. For example, a BASIC 
main module may need to execute a specific task that you would like to 
program separately. Instead of calling a BASIC subprogram, however, you 
decide to call a C function. 


Mixed-language calls necessarily involve multiple modules (at least with 
Microsoft languages). Instead of compiling all of your source modules with 
the same compiler, you use different compilers. In the example mentioned 
above, you would compile the main-module source file with the BASIC 
compiler, another source file (written in C) with the C compiler, and then 
link together the two object files. 
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Figure 1.1 illustrates how the syntax of a mixed-language call works, using 
the example mentioned above. 


DECLARE SUB Prn CDECL() 


Figure 1.1 Mixed-Language Call 


In the illustration above, the BASIC call to Cis CALL Prn, similar to a 
call to a BASIC subprogram. However, there are two differences between 
this mixed-language call and a call between two BASIC modules: 1) the 
subprogram Prn is actually implemented in C, using standard C syntax; 
and 2) the implementation of the call in BASIC is affected by DECLARE 
statement, which uses the CDECL keyword in order to create compatibil- 
ity with C. The DECLARE statement (which is discussed in detail in 
Chapter 2) is an example of a mixed-language “interface” statement. Each 
language. provides its own form of interface. 


Despite syntactic differences, functions, procedures, and FORTRAN sub- 
routines are all similar. The principal difference is that some kinds of rou- 
tines return values, and others do not. You can interchange routines that 
have a return value, and you can interchange routines that have no return 
value. (Note that in this manual, “routine” refers to any function, pro- 
cedure or subroutine that can be called from another module.) 
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Table 1.1 shows the correspondence between routine calls in different 
languages. 


Table 1.1 

Language Equivalents for Routine Calls 

Language Return value Noreturn value 
BASIC FUNCTION  subprogram 

procedure 

C | function (void) function 

FORTRAN function subroutine 

Pascal function procedure 

Macro Assembler procedure procedure 


For example, a BASIC module can make a subprogram call to a FOR- 
TRAN subroutine. BASIC should make a FUNCTION call in order to 
call a FORTRAN function; otherwise, the call can be made, but the return 
value will be lost. 


Note 


BASIC DEF FN functions and GOSUB subroutines cannot be called 
from another language. 


1.2 Naming Convention Requirement 


The term “naming convention” refers to the way that a compiler alters the 
name of the routine before placing it into an object file. 


It is important that you adopt a compatible naming convention when you 
issue a mixed-language call. If the name of the called routine is stored 
differently in each object file, then the linker will not be able to find a 
match. It will instead report an unresolved external. 


Microsoft compilers place machine code into object files; but they also 
place there the names of all routines and variables which need to be 
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accessed publicly. That way, the linker can compare the name of a routine 
called in one module to the name of a routine defined in another module, 
and recognize a match. Names are stored in ASCII (American Standard 
Code for Information Interchange) format. You can see precisely how they 
are stored if you use the DEBUG utility to dump an object file’s bytes. 


BASIC, FORTRAN, and Pascal use roughly the same naming convention. 
They translate each letter to uppercase. BASIC type declaration charac- 
ters (%, &, !, #, $) are dropped. 


However, each language recognizes a different number of characters. FOR- 
TRAN recognizes the first 6 characters of any name, Pascal the first 8, and 
BASIC the first 40. If a name is longer than the language will recognize, 
additional characters are simply not placed in the object file. 


C uses a quite different convention; the C compiler does not translate any 
letters to uppercase, but inserts a leading underscore (_ ) in front of the 
name of each routine. C recognizes the first 31 characters of a name. 


Differences in naming conventions are taken care of for you automatically 
by mixed-language keywords, as long as you follow two rules: 


1. If you are using any FORTRAN routines, all names should be 6 
characters or less in length. 


2. Do not use the /NOIGNORE linker option (which causes the 
linker to distinguish between Prn and prn). With C modules, 
this means that you will have to be careful not to rely upon 
differences between uppercase and lowercase letters. 


The CL driver and Microsoft QuickCm automatically use the 
/NOIGNORE option when linking. To solve the problems 
created by this behavior, either link separately with the LINK 
utility, or use all lowercase letters in your C modules. 


Figure 1.2 illustrates a complete mixed-language development example, 
showing how naming conventions enter into the process. 
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DECLARE SUB Prn CDECL() 


iler 


Comp 


PRN.OBJ 
object file) 


( 


object file) 


( 


@ 
7) 
a] 
Oo 
i) 
<) 
= 
a) 
c 
> 


( 


unless /NOBD 


call yyyy 


AAR 


a 


al 


os 


we 


a 


os 


Figure 1.2 Naming Convention 


11 


Microsoft Mixed-Language Programming Guide 


In the example above, note that the BASIC compiler inserts a leading 
underscore in front of Prn as it places the name into the object file, 
because the CDECL keyword directs the BASIC compiler to use the C 
naming convention. BASIC will also convert all letters to lowercase when 
this keyword is used. (Strictly speaking, converting letters to lowercase is 
not part of the C naming convention; however, it is consistent with the 
programming style of most C programs.) 


1.3 Calling Convention Requirement 


The term “calling convention” refers to the way that a language imple- 
ments a call. The choice of calling convention affects the actual machine 
instructions that a compiler generates in order to execute (and return 
from) a function, procedure, or subroutine call. 


The calling convention is a low-level protocol. It is crucial that the two 
routines concerned (the routine issuing a call and the routine being called) 
recognize the same protocol. Otherwise, the processor may receive incon- 
sistent instructions, thus causing the system to crash. 


The use of a calling convention affects programming in two ways: 


1. The calling routine uses a calling convention to determine in what 
order to pass arguments (parameters) to another routine. This con- 
vention can usually be specified in a mixed-language interface. 


2. The called routine uses a calling convention to determine in what 
order to recesve the parameters that were passed to it. In most 
languages, this convention can be specified in the routine’s head- 
ing. BASIC, however, always uses its own convention to receive 
parameters. 


In other words, each call to a routine uses a certain calling convention, and 
each routine heading specifies or assumes some calling convention. The two 
conventions must be compatible. With each language except BASIC, it is 
possible to change either calling convention. Usually, however, it is sim- 
plest to adopt the convention of the called routine. For example, a C func- 
tion would use its own convention to call another C function, and use the 
Pascal convention to call Pascal. 


BASIC, FORTRAN, and Pascal use the same standard calling convention. 
C, however, uses a quite different convention. 
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Note 


The next few paragraphs discuss some of the details of calling conven- 
tions. It is not crucial for a high-level language programmer to under- 
stand these details; the programmer only needs to know that the dif- 
ferent conventions are not compatible with each other. 


The Microsoft BASIC, FORTRAN and Pascal calling conventions each 
push parameters onto the stack in the order in which they appear in the 
source code. For example, the BASIC statement CALL Calc (A,B) 
pushes the argument A onto the stack before it pushes B. These conven- 
tions also specify that the stack is restored by the called routine, just 
before returning control to the caller. (The stack is restored by removing 
parameters. ) 


The C calling convention pushes parameters onto the stack in the reverse 
order in which they appear in the source code. For example, the C function 
call calc(a,b); pushes b onto the stack before it pushes a. In con- 
trast with the other high-level languages, the C calling convention specifies 
that a calling routine always restores the stack immediately after the 
called routine returns control. 


The BASIC, FORTRAN, and Pascal conventions produce slightly less 
object code. However, the C convention makes calling with a variable 
number of parameters possible. (Because the first parameter is always the 
last one pushed, it is always on the top of the stack; therefore it has the 
same address relative to the frame pointer, regardless of how many param- 
eters were actually passed.) 


1.4 Parameter-Passing Requirement 


Section 1.3 discussed the overall protocol (the calling convention) that two 
routines use to communicate with each other; this section concerns how an 
individual piece of data (a parameter) is actually sent. 


If your routines do not agree on how a parameter is to be sent, then a 


called routine will receive bad data. It is also possible that the program 
could cause the system to crash. 
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Microsoft compilers support three methods for passing a parameter: 


Method Description 


By near reference Passes a variable’s near (offset) address. 


This method gives the called routine direct 
access to the variable itself. Any change the rou- 
tine makes to the parameter will be reflected in 
the calling routine. 


By far reference Passes a variable’s far (segmented) address. 


This method is similar to passing by near refer- 
ence, except that a longer address is passed. 
This method is slower than passing by near 
reference but is necessary when you pass data 
that is outside of the default data segment. 
(This is not an issue in BASIC or Pascal, unless 
you have specifically requested far memory.) 


By value Passes only the variable’s value, not address. 


With this method, the called routine knows the 
value of the parameter, but has no access to the 
original variable. Changes to a value parameter 
have no affect on the value of the parameter in 

the calling routine, once the routine terminates. 


The fact that there are different parameter-passing methods has two 
implications for mixed-language programming. 


First, you need to make sure that the called routine and the calling rou- 
tine use the same method for passing each parameter (argument). In most 
cases, you will need to check the parameter-passing defaults used by each 
language, and possibly make adjustments. Each language has keywords or 
language features that allow you to change parameter-passing methods. 


Second, you may want to use a particular parameter-passing method 
rather than using the defaults of any language. (In fact, the examples in 
Chapters 2-5 specifically require one particular method or another, 
because of program logic.) 


Table 1.2 summarizes the parameter-passing defaults for each language. 
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Table 1.2 

Parameter-Passing Defaults 

Language Near reference Far reference By value 
BASIC all 

C near arrays far arrays non-arrays 
FORTRAN all all! 

Pascal VAR, CONST VARS, CONSTS other params 


1 When a PASCAL or C attribute is applied to a FORTRAN routine, pass by value becomes 
the default. 


Each language has methods for overriding these defaults, which are listed 
in Chapter 7. 


1.5 Compiling and Linking 


After you have written your source files and resolved the issues raised in 
Sections 1.2-1.4, you are ready to compile individual modules and then 
link them together. 


1.5.1 Compiling with Proper Memory Models 


With Microsoft BASIC, FORTRAN, and Pascal, no special options are 
required to compile source files that are part of a mixed-language program. 


With Microsoft C, however, you need to be aware that not all memory 
models will be compatible with other languages. BASIC, FORTRAN, and 
Pascal use only far Pee!) code addresses. Therefore, you must al- 
ways compile C modules in medium, large, or huge model, because these 
models also use far code addresses. Compiling in small or compact model 
will cause the mixed-language program to crash, as soon as a call is made 
to or from C. (This problem can be averted if you apply the far keyword 
to a C function definition, in order to specify that the function uses a far 
call and return.) 
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The paragraph above concerns the size of code addresses. Differences in 
the size of data addresses can be resolved through compile options or in 
the source code. Choice of memory model affects the default data pointer 
size in C and FORTRAN, although this default can be overriden with 
near and far. Choice of memory model, with C and FORTRAN, also 
affects whether data objects are located in the default data segment; if a 
data object is not located in the default data segment, it cannot be 
directly passed by near reference. 


1.5.2 Linking with Language Libraries 


In many cases, linking modules compiled with different languages can be 
done easily. Any of the following measures will ensure that all of the 
required libraries are linked in the correct order: 


e Put all language libraries in the same directory as the source files. 


e List directories containing all needed libraries in the LIB environ- 
ment variable. 


e Let the linker prompt you for libraries. 


In each of the above cases, the linker finds libraries in the order that it 
requires them. If you enter the libraries on the command line, then they 
must be entered in a particular order. 


However, if you are using, Version 4.0 of FORTRAN to produce one 

of your modules, then you will need to link with /NOD (no default 
libraries), and specify all the libraries you need directly on the link 
command-line. You can also specify these libraries with an automatic- 
response file (or batch file), but you cannot use a default library search. 


With the FORTRAN 4.0 C-compatible library, make sure that you specify 
the FORTRAN library before you specify the C library, unless your ver- 
sion of C is more recent than your version of FORTRAN, in which case 
specify the C library first. Otherwise, any other libraries you specify may 
go in any order. 


If you are listing BASIC libraries on the LINK command-line, the BASIC 
libraries must precede all others. 

=H Example 

LINK /NOD modl1 mod2,,,GRAFX+LLIBFORE+LLIBC 


The example above links two object modules with the FORTRAN 4.0 and 
C large model libraries. In addition, an extra library, GRAFX, is linked in. 
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BASIC Calls to High-Level Languages 


Microsoft BASIC supports calls to routines written in Microsoft C, FOR- 
TRAN, and Pascal. This chapter describes the necessary syntax for calling 
these other languages, and then gives examples for each combination of 
BASIC with another language. Only integers are used as parameters in 
these examples. 


The chapter ends with a section that lists restrictions on the use of func- 
tions from the C standard library. Consult this section if you are using any 
memory allocation or system library functions. 


For information on how to pass specific kinds of data, consult Part 2, 
“Data Handling Reference.” 


2.1 The BASIC Interface to Other Languages 


The BASIC DECLARE statement provides a flexible and convenient 
interface to other languages. It is available with Microsoft QuickBASIC, 
Versions 4.0 and later. Versions that do not provide the DECLARE 
statement do not provide libraries that are compatible with other lan- 
guages, either. These earlier versions have limited use in mixed-language 
programs, as they cannot successfully call a C, FORTRAN, or Pascal rou- 
tine that makes any use of a library. 


The syntax of the DECLARE statement is summarized below. 


2.1.1 The DECLARE Statement 

When you call a function, the DECLARE statement syntax is as follows: 
DECLARE FUNCTION name [CDECL]/ALIAS "aliasname"||(parameter-list)] 
When you call a subprogram, the statement syntax is as follows: 
DECLARE SUB name [CDECL][ALIAS “aliasname"||(parameter-list)] 


The name field is the name of the function or subprogram procedure you 
wish to call, as it appears in the BASIC source file. Here are the recom- 
mended steps for using the DECLARE statement to call other languages: 


1. For each distinct interlanguage routine you plan to call, put a 
DECLARE statement in the BASIC source file before the routine 
is called. 


For example, your program may call the subprogram Maxparam 
five different times, each time with different arguments. However, 
you need to declare Maxparam just once. Ideally, DECLARE 

statements should be placed near the beginning of the source file. 
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2. If you are calling a routine from a C module, use CDECL in the 
DECLARE statement (unless the C routine is declared with the 
pascal or fortran keyword). 


CDECL directs BASIC to use the C naming and calling conven- 
tions during each subsequent call to name. No similar keywords = 
are provided for Pascal or FORTRAN, because they each use the 
same calling convention as BASIC. 


3. If you are calling a FORTRAN routine with a name longer than six 
characters, or a C or Pascal routine with a name longer than eight 
characters, use the ALIAS feature. The use of ALIAS 1s explained 


in the section below. 


4. Use the parameter list to determine how each parameter is to be 
passed. The use of the parameter list is explained below, in the sec- 
tion immediately after the information on ALIAS. 


5. Once the routine is properly declared, call it just as you would a 
BASIC subprogram or function. 


The other fields are explained in the following discussion. 


2.1.2 Using ALIAS 


As noted above, the use of ALIAS may be necessary because FORTRAN 
places only the first 6 characters of a name into an object file, whereas C 
and Pascal each place the first 8, but BASIC will place up to 40 characters 
of a name into an object file. 


Note 


You do not need the ALIAS feature to remove type declaration char- 

acters (%, &,!, #, 5). BASIC automatically removes these characters 

when it generates object code. Thus, Fact% in BASIC matches Fact 
in Pascal. 


The ALIAS keyword directs BASIC to place alzasname into the object file, 
instead of name. The BASIC source file still contains calls to name. How- 
ever, these calls are interpreted as if they were actually calls to aliasname. 


@ Example 


DECLARE FUNCTION Quadratic% ALIAS "QUADRA" (a, b, c) 
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In the example above, QUADRA, the aliasname, contains the first six char- 
acters of Quadratic%, the name. This causes BASIC to place QUADRA 
into the object code, thereby mimicking FORTRAN’s behavior. 


2.1.3 Using the Parameter List 


The parameter list syntax is displayed below, followed by explanations of 
each field. Note that you can use BYVAL or SEG, but not both. 


@ Syntax 
[BYVAL | SEG] variable [AS type..., 


Use the BYVAL keyword to declare a value parameter. In each subse- 
quent call, the corresponding argument will be passed by value (the 
default method for O and Pascal modules). 


Note 


BASIC provides two ways of “passing by value.” The usual method of 
passing by value is to use an extra set of parentheses, as in: 


CALL Holm ( (A) ) 


This method actually creates a temporary value, whose address is 
passed. BYVAL provides a true method of passing by value, because 
the value itself is passed, not an address. Only by using BYVAL will a 
BASIC program be compatible with a non-BASIC routine that expects 
a value parameter. 


Use the SEG keyword to declare a far reference parameter. In each subse- 
quent call, the far (segmented) address of the corresponding argument will 


be passed (the default method for FORTRAN modules). 


You can choose any legal name for variable; but only the type associated 
with the name has any significance to BASIC. As with other variables, the 
type can be indicated with a type declaration character (%, &, !, #, $) or 
by implicit declaration. 


You can use the AS type clause to override the type declaration of 
variable. The type field can be INTEGER, LONG, SINGLE, 
DOUBLE, STRING, a user-defined type, or ANY, which directs BASIC 
to permit any type of data to be passed as the argument. 
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m Examples 
DECLARE FUNCTION Calc2! CDECL (BYVAL a%, BYVAL b%, BYVAL c!) 


In the example above, Calc2 is declared as a C routine that takes three 
arguments: the first two are integers passed by value, and the last is a 
single-precision real number passed by value. 


DECLARE SUB Maxout (SEG varl AS INTEGER, BYVAL var2 AS DOUBLE) 


This example declares a subprogram Maxout that takes an integer passed 
by far reference, and a double-precision real number passed by value. 


2.2 Alternative BASIC Interfaces 


Though the DECLARE statement provides a particularly convenient 
interface, there are other methods of implementing mixed-language calls. 


Instead of modifying the behavior of BASIC with CDECL, you can 
modify the behavior of C by applying the pascal or fortran keyword to 
the function definition heading. (These two keywords are functionally 
equivalent). Or you can compile the C module with the /Ge option, which 
specifies that all C functions, calls, and public symbols use the conventions 


of BASIC/FORTRAN/Pascal. 
For example, the following C function uses the BASIC/FORTRAN/Pascal 


conventions to receive an integer paramter: 


int pascal funl1(n) 
int n; 


You can specify parameter-passing methods without using a DECLARE 
statement or by using a DECLARE statement and omitting the parame- 
ter list. 


e You can make the call with the CALLS statement. The CALLS 
statement causes each parameter to be passed by far reference. 


e You can use the BYVAL and SEG keywords in the actual param- 
eter list when you make the call: 


CALL Fun2 (BYVAL Termi, BYVAL Term2, SEG Sum); 


In the example above, BYVAL and SEG have the same meaning that 
they have in a BASIC DECLARE statement. When you use BY VAL and 
SEG this way, however, you need to be careful because neither the type 
nor the number of parameters will be checked as they would be in a 
DECLARE statement. 
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2.3 BASIC Calls to C 


This section applies the steps outlined in Section 2.1 to two example pro- 
grams. An analysis of programming considerations follows each example. 


2.3.1 Calling C from BASIC—No Return Value 


The example below demonstrates a BASIC main module calling a C func- 
tion, maxparam. The function maxparam returns no value, but adjusts 
the lower of two arguments to equal the higher argument. 


uw Example 


' BASIC source file - calls C function returning no value 
t 
DECLARE SUB Maxparam CDECL (A AS INTEGER, B AS INTEGER) 
t 
' DECLARE as subprogram, since there is no return value 


' CDECL keyword causes Maxparam call to be made w/ C conventions 
' Integer parameters passed by near reference (BASIC default) 
t 


XY = 5 
YY = | 

PRINT USING "X% = ## Y% = ##":X% 3 YY ' X% and Y¥% before call 
CALL Maxparam (X%, Y%) | ' Call C function 
PRINT USING "X% = ## YX = #4": X% 3 YY ' X% and Y% after call 


END 

/* C source file +/ 

/* Compile in MEDIUM or LARGE memory model +/ 

/* Maxparam declared VOID because no return value «/ 


void maxparam(pl, p2) 


int near «pl; /* Integer params received by near ref. «/ 
int near *p2; /* NEAR keyword not needed in MEDIUM model +«/ 
{ 
if («pl > +*p2) 
xp2Z = *pl; 
else 
*pl = *p2; 


} 


Naming conventions: The CDECL keyword causes Maxparam to be 
called with the C naming convention (as _maxparam). Note that word 
length is not an issue because maxparam does not exceed eight charac- 
ters. 
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Calling conventions: The CDECL keyword causes Maxparam to be 
called with the C calling convention, which pushes parameters in the re- 
verse order to how they appear in the source code. 


Parameter-passing methods: Since the C function maxparam may 
alter the value of either parameter, both parameters must be passed by 
reference. In this case, near reference was chosen; this method is the de- 
fault for BASIC (so neither BYVAL nor SEG is used) and is specified in 
C by using near pointers. 


Far reference could have been specified by applying SEG to each argu- 
ment in the DECLARE statement. In that case, the C parameter decla- 
rations would use far pointers. 


2.3.2 Calling C from BASIC—Function Call 


The example below demonstrates a BASIC main module calling a C func- 
tion, fact. This function returns the factorial of an integer value. 


mB Example 


" BASIC source file - calls C function with return value 
' 


DECLARE FUNCTION Fact% CDECL (BYVAL N AS INTEGER) 


' DECLARE as function returning integer (%) 

' CDECL keyword causes Fact% call to be made w/ C conventions 
' Integer parameter passed by value 

! 


X¥% = 3 
Y% = 4 

PRINT USING "The factorial of XY¥ is ####"; Fact% (X%) 
PRINT USING "The factorial of YY% is #H###"; Fact% (Y%) 
PRINT USING "The factorial of X¥+Y% is #HHH": FactY (XY%+Y%) 
END 


/* C source file «/ 
f/x Compile in MEDIUM or LARGE model +/ 
/* Factorial function, returning integer «/ 


int fact (n) 
int 71; /* Integer passed by value, the C default «/ 


§ 


int result = lL: 
while (n > 0) 


result *= n--; /* Parameter n modified here «/ 
return (result); 
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Naming conventions: The CDECL keyword causes Fact to be called 
with the C naming convention (as _fact). Note that word length is not 
an issue because fact does not exceed eight characters. 


Calling conventions: The CDECL keyword causes fact to be called 
with the C calling convention, which pushes parameters in reverse order 
and specifies other low-level differences. 


Parameter-passing methods: The C function above should receive the 
parameter by value. Otherwise the function will corrupt the parameter’s 
value in the calling module. True passing by value is achieved in BASIC 
only by applying BYVAL to the parameter in the DECLARE statement; 
in C, passing by value is the default (except for arrays). 
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2.4 BASIC Calls to FORTRAN 


This section applies the steps outlined in Section 2.1 to two example pro- 
grams. An analysis of programming considerations follows each example. 


2.4.1 Calling FORTRAN from BASIC— 
Subroutine Call 


The example below demonstrates a BASIC main module calling a FOR- 
TRAN subroutine, MAXPARAM. The subroutine returns no value, but 
adjusts the lower of two arguments to equal the higher argument. 


mw Example 


' BASIC source file - calls FORTRAN subroutine 
t 
DECLARE SUB Maxparam ALIAS "MAXPAR" (A AS INTEGER, B AS INTEGER) 
t 
' DECLARE as subprogram, since there is no return value 


' ALIAS needed because FORTRAN recognizes only first 6 letters 
' Integer parameters passed by near reference (BASIC default) 


X% = 5 
Y% = 
PRINT USING "X¥ = ## Y% = HH'SXY 3 Y% ' X% and Y% before call 
CALL Maxparam (X%, Y%) ' Call FORTRAN function 
PRINT USING "X¥% = #4 Y% = #4":X% :Y% ' X% and Y¥% after call 
END 
C FORTRAN source file, subroutine MAXPARAM 
Cc 

SUBROUTINE MAXPARAM (I, J) 

INTEGER4+2 I [NEAR] 

INTEGER*«2 J [NEAR] 
Cc 
C I and J received by near reference, because of NEAR attribute 
Cc 

IF (I .GT. J) THEN 

| J=TI 
ELSE 
IT=J 
ENDIF 
END 


Naming conventions: By default, BASIC places all eight characters of 
Maxparam into the object file, yet FORTRAN places only the first six. 
This conflict is resolved with the ALIAS feature: both modules place 
MAXPAR into the object file. 
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Calling conventions: BASIC and FORTRAN use the same convention 
for calling. 


Parameter-passing methods: Since the subprogram Maxparam may 
alter the value of either parameter, both arguments must be passed by 
reference. In this case, near reference was chosen; this method is the de- 
fault for BASIC (so neither BYVAL nor SEG is used) and is specified in 
FORTRAN by applying the NEAR attribute to each of the parameter 
declarations. 


Far reference could have been specified by applying SEG to each argu- 
ment in the DECLARE statement. In that case, the NEAR attribute 
would not be used in the FORTRAN code. 


2.4.2 Calling FORTRAN from BASIC— 
Function Call 


The example below demonstrates a BASIC main module calling a FOR- 
TRAN function, FACT. This function returns the factorial of an integer 
value. | 


gS Example 


' BASIC source file - calls FORTRAN function 


DECLARE FUNCTION Fact®% (BYVAL N AS INTEGER) 


' DECLARE as function returning integer (%) 
' Integer parameter passed by value 
f 


PRINT USING "The factorial of X% is #H#HH"> Fact% (X%) 
PRINT USING "The factorial of YY is ####"; Fact% (Y%) 
PRINT USING "The factorial of X%+Y% is ##H##"; Fact% (X%+Y%) 
END 


C FORTRAN source file - factorial function 


C 
INTEGER*2 FUNCTION FACT (N) 
INTEGER*2 N [VALUE] 
C 
Cc N is received by value, because of VALUE attribute 
C 


INTEGER*2 I 
FACT = 1 
DO 100 I =1, N 
FACT = FACT « I 
100 CONTINUE 
RETURN 
END 
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Naming conventions: There are no conflicts with naming conventions 
because the function name, FACT, does not exceed six characters. The 
type declaration character (%) is automatically dropped by BASIC. 


Calling conventions: BASIC and FORTRAN use the same convention 
for calling. 


Parameter-passing methods: When a parameter is passed that should 
not be changed, it is generally safest to pass the parameter by value. True 
passing by value is specified in BASIC by applying BY VAL to an argu- 
ment in the DECLARE statement; in FORTRAN, passing by value is 
achieved by applying the VALUE attribute to a parameter declaration. 
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2.5 BASIC Calls to Pascal 


This section applies the steps outlined in Section 2.1 to two example pro- 
grams. An analysis of programming considerations follows each example. 


2.5.1 Calling Pascal from BASIC— 
Procedure Call 


The example below demonstrates a BASIC main module calling a Pascal 
procedure, Maxparam. Maxparam returns no value, but adjusts the 
lower of two arguments to equal the higher argument. 


m Example 


' BASIC source file - calls Pascal procedure 
t 


DECLARE SUB Maxparam (A AS INTEGER, B AS INTEGER) 


' DECLARE as subprogram, since there is no return value 
' Integer parameters passed by near reference (BASIC default) 
t 


X% = 5 

4= 
PRINT USING "X% = ## Y% = ##":X% 3 YY ' X% and Y¥% before call 
CALL Maxparam (X%, Y%) ' Call Pascal function 
PRINT USING "X% = ## Y% = #8":XY% :Y% =" X% and YY after call 
END 


{ Pascal source code - Maxparam procedure. } 


module Psub; 
procedure Maxparam(var a:integer; var b:integer); 


{ Two integer parameters are received by near reference. } 
{ Near reference is specified with the VAR keyword. } 


begin 
if a > b then 
b s=a 
else 
as:= b 
end: 
end. 


Naming conventions: Note that word length is not an issue because 
Maxparam does not exceed eight characters. 


Calling conventions: BASIC and Pascal use the same calling convention. 
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Parameter-passing methods: Since the procedure Maxparam may 
alter the value of either parameter, both parameters must be passed by 
reference. In this case, near reference was chosen; this method is the de- 
fault for BASIC (so neither BY VAL nor SEG is used) and is specified in 
Pascal by declaring parameters as VAR. 


Far reference could have been specified by applying SEG to each argu- 
ment in the DECLARE statement. In that case, the VARS keyword 
would be required instead of VAR. 


2.5.2 Calling Pascal from BASIC— 
Function Call 


The example below demonstrates a BASIC main module calling a Pascal 
function, Fact. This function returns the factorial of an integer value. 


m Example 


" BASIC source file - calls Pascal function 
DECLARE FUNCTION Fact% (BYVAL N AS INTEGER) 


' DECLARE as function returning integer (%) 

' Integer parameter passed by value 

X% = 3 

Y¥ = 4 

PRINT USING "The factorial of X% is ####"; Fact (X%) 
PRINT USING "The factorial of YY% is ####"; Fact% (Y%) 
PRINT USING "The factorial of X%+Y% is ####"; Fact% (X%+Y%) 
END 


{ Pascal source code - factorial function. } 


module Pfun; 
function Fact (n : integer) : integer; 


{ Integer parameters received by value, the Pascal default. } 


begin 
Fact := 1: 
while n > O do 
begin 
Fact := Fact * n>? 
ns:=n- 1; { Parameter n altered here. } 
end: 
end; 
end. 
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Naming conventions: Note that word length is not an issue because 
fact does not exceed eight characters. 


Calling conventions: BASIC and Pascal use the same calling convention. 


Parameter-passing methods: The Pascal function above should receive 
a parameter by value. Otherwise the function will corrupt the parameter’s 
value in the calling module. True passing by value is achieved in BASIC 
only by applying BY VAL to the parameter; in Pascal, passing by value is 
the default. 


2.6 Restrictions on Calls from BASIC 


BASIC has a much more complex environment and initialization procedure 
than C, FORTRAN, or Pascal (all of which use a similar environment). 
Interlanguage calling between BASIC and these other languages is possible 
only because BASIC intercepts a number of library function calls from the 
other languages and handles them in its own way. In other words, BASIC 
creates a host environment in which the C, FORTRAN, and Pascal library 
routines can function. 


However, BASIC is limited in its ability to handle some C function calls. 
This section considers two kinds of limitations: C memory-allocation func- 
tions, which may require a special declaration, and C library functions, 
which cannot be called at all. 


2.6.1 Memory Allocation 


If your C module is medium model and you do dynamic memory allocation 
with malloc(), or if you execute explicit calls to _nmalloc() with any 
memory model, then you need to include the following lines in your BASIC 
source code before you call C: 


DIM mallocbuf% (2048) 
COMMON SHARED /NMALLOC/ mallocbufY% () 


The array can have any name; only the size of the array is significant. 
However, the name of the common block must be NMALLOC., In the 
QuickBASIC, Version 4.0, in-memory environment, you need to put this 
declaration in a module that you load into a resident Quick library. 


The example above has the effect of reserving 4k bytes of space in the com- 


mon block NMALLOC. When BASIC intercepts C malloc calls, BASIC 
allocates space out of this common block. 
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Warning 
When you call the BASIC intrinsic function CLEAR, all space allo- 


cated with near malloc calls will be lost. If you use CLEAR at all, use 


it only before any calls to malloc. 


When you make far memory requests in mixed-language programs, you 
may find it useful to first call the BASIC intrinsic function SETMEM. 
This function can be used to reduce the amount of memory BASIC is 
using, thus freeing up memory for far allocations. 


2.6.2 Incompatible Functions 


The following C functions are incompatible with BASIC and should be 
avoided: 


e All forms of spawn() and exec() 


e system() 
e getenv() 
e putenv() 


In addition, you should not link with the zVARSTK.OBJ modules 
(where zis a memory model), which C provides to allocate memory from 
the stack. 
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C Calls to High-Level Languages 


Microsoft C supports calls to routines written in Microsoft FORTRAN and 
Pascal. Also, if the main program is in BASIC, then a C routine can call a 
BASIC routine. This chapter describes the necessary syntax for calling 
these other languages, and then gives examples for each language. Only 
simple parameter lists are used in this chapter. 


For information on how to pass particular kinds of data, consult Part 2, 
“Data Handling Reference.” 


3.1 The C Interface to Other Languages 


The C interface to other languages utilizes the standard C extern state- 
ment, combined with the special fortran or pascal keyword. Using either 
of these keywords causes the routine to be called with the naming and cal- 
ling conventions of FORTRAN/Pascal/BASIC. Here are the recommended 


steps for using this statement to execute a mixed-language call from C: 


1. Write an extern statement for each mixed-language routine called. 


The extern statement should precede all calls to the routine. The 
exact rules of syntax for using the fortran and pascal keywords 
with the extern statement are presented below. 


Instead of using the fortran or pascal keyword, you can simply 
compile with /Ge. The /Ge option causes all functions in the 
module to use the BASIC/FORTRAN/Pascal naming and calling 
conventions, except where you apply the cdecl keyword. 

2. Use parameter type declarations within the extern statement. 


This step is essential if you are going to specify pointers that are 
not the default size. (Near pointers are the default for medium 
model; far pointers are the default for large model.) 


3. To pass an argument by reference, pass a pointer to the object. 


C automatically translates array names into addresses. Therefore, 
arrays are automatically passed by reference. 


4. Once a routine has been properly declared with an extern state- 
ment, call it just as you would call a C function. 


5. Always compile the C module in medium or large model. 
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= Using fortran and pascal Keywords 


There are two rules of syntax that apply when you use the fortran or 
pascal keyword: 


1. The fortran and pascal keywords modify the item immediately to 
the right. 


2. The special near and far keywords can be used with the fortran 
and pascal keywords in declarations. The sequences fortran far 
and far fortran are equivalent. 


The keywords pascal and fortran actually have the same effect on the 
program; the use of one or the other makes no difference except for docu- 
mentation purposes. Use either keyword to declare a BASIC routine. 


The following examples demonstrate the syntax rules presented above. 


= Examples 
extern short pascal thing(short, short); /*x Example 1 «/ 


Example 1 declares thing to be a BASIC, Pascal, or FORTRAN function 
taking two short parameters and returning a short value. 


extern void (fortran *thing) (long); /* Example 2 «/ 


Example 2 declares thing to be pointer to a BASIC, Pascal, or FOR- 
TRAN routine that takes a long parameter and returns no value. The key- 
word void is appropriate when the called routine is a BASIC subprogram, 
Pascal procedure, or FORTRAN subroutine, since it indicates that no 
return value is required. 


extern short near pascal thing(double +); /* Example 3 «/ 
Example 3 declares thing to be a near BASIC, Pascal, or FORTRAN 
routine. The routine receives a double parameter by reference (because it 
expects a pointer to a double) and returns a short value. 


extern short pascal near thing(double +); /* Example 4 «/ 


Example 4 is equivalent to Example 3( pascal near is equivalent to 
near pascal). 
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3.2 Alternative C Interfaces 


When you call BASIC, you must use the BASIC/FORTRAN/Pascal con- 
ventions to make the call. When you call FORTRAN or Pascal, however, 
you have a choice. You can make C adopt the appropriate conventions (as 
described in the previous section), or you can make the FORTRAN or Pas- 
cal routine adopt the C conventions. 


To make a FORTRAN or Pascal routine adopt the C conventions, simply 
put the C attribute in the heading of the routine’s definition. The follow- 
ing example demonstrates the syntax for the C attribute in a FORTRAN 
subroutine-definition heading: 


SUBROUTINE FFROMC [C] (N) 
INTEGER+2 N 


The following example demonstrates the syntax for the C attribute in a 
Pascal procedure-definition heading: 


module Pmod; 
procedure Pfromc (n : integer) [C]; 
begin 


3.3 C Calls to BASIC 


No BASIC routine can be executed unless the main program is in BASIC, 
because a BASIC routine requires the environment to be initialized in a 
way that is unique to BASIC. No other language will perform this special 
initialization. 

However, it 1s possible for a program to start up in BASIC, call a C func- 
tion that does most of the work of the program, and then call BASIC sub- 
programs and function procedures as needed. Figure 3.1 illustrates how 
this can be done. 

The following rules are recommended when you call BASIC from C: 


1. Start up in a BASIC main module. You will need to use Quick- 
BASIC, Version 4.0 or later, and the DECLARE statement to 
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provide an interface to the C module. (See Chapter 2, “BASIC 
Calls to High-Level Languages,” for more information. ) 


Once in the C module, declare the BASIC routine as extern, and 
include type information for parameters. Use either the fortran or 
pascal keyword to modify the routine itself. 


Make sure that all data are passed as a near pointer. BASIC can 
pass data in a variety of ways, but is unable to receive data in any 
form other than near reference. 


With near pointers, the program assumes that the data are in the 
default data segment. If you want to pass data that are not in the 
default data segment (this is only a consideration with large-model 
programs), then first copy the data to a variable that is in the 
default data segment. 


Compile the C module in medium or large model. 


(BASIC start-up) 


CALL Csub eae 
END void csub(){ 


(BASIC termination) 


SUB Btest STATIC 


END SUB 


Figure 3.1 C Call to BASIC 


The example below demonstrates a BASIC program that calls a C func- 
tion. The C function then calls a BASIC function that returns twice the 
number passed it and a BASIC subprogram that prints two numbers. 
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= Example 


* BASIC source 

DEFINT A-Z 

DECLARE SUB Cprog CDECL() 
CALL Cprog 

END 


FUNCTION Db1(N) STATIC 
Dbl = Nx2 
END FUNCTION 


SUB Printnum(A,B) STATIC 
PRINT "The first number is ":A 
PRINT "The second number is ";B 
END SUB 


/*x C source; compile in medium or large model */ 


extern int fortran dbl (int near *); 
extern void fortran printnum(int near *, int near *); 


void cprog() 
{ 


5: /* NEAR guarantees that the data +«/ 
6; /* will be placed in default x / 
/* data segment (DGROUP) */ 


int near a 
int near b 


printf ("Twice of 5 is %d\n", dbl (&a)): 
printnum(&a, &b); 
} 


In the example above, note that the addresses of a and b are passed, 
since BASIC expects to receive addresses for parameters. Also note that 
the keyword near is used to declare each pointer; this keyword would be 
unnecessary if we knew the C module was compiled in medium model 
rather than large. 


Calling and naming conventions are resolved by the CDECL keyword in 
BASIC’s declaration of Cprog, and by fortran in C’s declaration of dbl 
and printnum. 


Note 


QuickBASIC 4.0 provides a number of “user-entry points,” which are 
BASIC system-level functions that may be called directly from C. 
These functions provide memory management, C-string services, and 


I/O procedures. Check the README file provided with QuickBASIC 
4.0 for further information. 
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3.4 C Calls to FORTRAN 


This section applies the steps outlined in Section 3.1 to two examples of 
C-FORTRAN programs. A brief analysis follows each example. 


3.4.1 Calling FORTRAN from C— 
Subroutine Call 


The example below demonstrates a C main module calling a FORTRAN 
subroutine, maxpar. This subroutine adjusts the lower of two arguments 
to equal the higher argument. 


m Example 


/* C source file - calls FORTRAN subroutine *«/ 
/* Compile in MEDIUM or LARGE model +/ 


extern void fortran maxpar (int near +, int near *); 


/* Declare as VOID, because there is no return value *«/ 

/* FORTRAN keyword causes C to use BASIC/FORTRAN/Pascal 
calling and naming conventions x / 

/* Two integer params, passed by near reference +/ 


main () 
af 
int a= Ss 
int..b-= 7? 
printf("a = %d, b = ¥d", a, b); 
maxpar (&a, &b); 
printf("a = %d, b = %a", a, b): 
C FORTRAN source file, subroutine MAXPARAM 
Cc 


SUBROUTINE MAXPARAM (I, J) 
INTEGER*2 I [NEAR] 
INTEGER+2 J [NEAR] 


e 
C I and J received by near reference, because of NEAR attribute 
C 
IF (I .GT. J) THEN 
J=I 
ELSE 
IT=J 
ENDIE 
END 
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Naming conventions: The fortran keyword directs C to call maxpar 
with the BASIC/FORTRAN/Pascal naming convention (as MAXPAR). 
Note that maxpar is six letters long; it cannot be any longer because 
FORTRAN only recognizes the first six characters of any name. 


Calling conventions: The fortran keyword directs C to call maxpar 


with the BASIC/FORTRAN/Pascal calling convention. 


Parameter-passing methods: Since the FORTRAN subroutine maxpar 
may alter the value of either parameter, both parameters must be passed 
by reference. In this case, near reference was chosen; this method is spec- 
ified in C by the use of near pointers, and in FORTRAN by applying the 
NEAR keyword to the parameter declarations. 


Far reference could have been specified by using far pointers in C. In that 

case, the FORTRAN subroutine would not use the NEAR attribute (and 

would require the FAR attribute if compiled with medium memory model 
available with FORTRAN, Version 4.0). 


3.4.2 Calling FORTRAN from C— 
Function Call 


The example below demonstrates a C main module calling a FORTRAN 
function, fact. This function returns the factorial of an integer value. 


m Example 


/* C source file - calls FORTRAN function +«/ 
/* Compile in MEDIUM or LARGE model +/ 


extern int fortran fact (int); 
/* EORTRAN keyword causes C to use BASIC/FORTRAN/Pascal 


calling and naming conventions x / 
/x Integer parameter passed by value, the C default «/ 


main () 
int x = 3; 
int y = 4; 
printf ("The factorial of x is 44d", fact (x)); 
printf("The factorial of y is 44d", fact(y)); 
printf ("The factorial of xty is %4d", fact (xty)); 
} 
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C FORTRAN source file - factorial function 
C 


INTEGER*2 FUNCTION FACT (N) 
INTEGER+2 N [VALUE] 


C 
C N is received by value, because of VALUE attribute ce 
e 


INTEGER*2 I 


100 CONTINU 


Naming conventions: The fortran keyword directs C to call fact with 
the aay Gea ae Pascal naming convention (as FACT). Note that 
word length is not an issue because FACT does not exceed six characters. 


Calling conventions: The fortran keyword directs C to call fact with 
the BASIC/FORTRAN/Pascal calling convention. 


Parameter-passing methods: When a parameter is passed that should 
not be changed, it is generally safest to pass the parameter by value. Pass- 


ing by value is the default method in C, and is specified in FORTRAN by 
applying the VALUE attribute to the parameter declaration. 


3.5 C Calls to Pascal 


This section applies the steps outlined in Section 3.1 to two examples of 
C-Pascal programs. A brief analysis follows each example. | 


3.5.1 Calling Pascal from C—Procedure Call 


The example below demonstrates a C main module calling a Pascal pro- 
cedure, maxpar. This procedure adjusts the lower of two arguments to 
equal the higher argument. 


m@ Example 


/x C source file - calls Pascal procedure +/ 
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/* Compile in MEDIUM or LARGE model +«/ 
extern void pascal maxparam (int near *, int near *); 


/* Declare as VOID, because there is no return value +«/ 

/* PASCAL keyword causes C to use BASIC/FORTRAN/Pascal 
calling and naming conventions x / 

/*x Two integer params, passed by near reference +/ 


main () 
r 
int a = 5; 
int b = 7; 
printf("a = %d, b = %d", a, b); 
maxparam(&a, &b); 
printf ("a = %d, b = %d", a, b); 
} 


{ Pascal source code - Maxparam procedure. } 


module Psub; 
procedure Maxparam(var a:integer; var b:integer); 


{ Two integer parameters are received by near reference. } 
{ Near reference is specified with the VAR keyword. } 


begin 
if a > b then 
b s=a 
else 
a:=b 
end: 
end. 


Naming conventions: The pascal keyword directs C to call Maxparam 
with the BASIC / FORTRAN Pascal naming convention (as MAXPARAM). 


Calling conventions: The pascal keyword directs C to call Maxparam 
with the BASIC/FORTRAN/Pascal naming convention. 


Parameter-passing methods: Since the procedure Maxparam may 
alter the value of either parameter, both parameters must be passed by 
reference. In this case, near reference is used; this method is specified in C 
by the use of near pointers, and in Pascal with the VAR keyword. 


Far reference could have been specified by using far pointers in C. In that 
case, the VARS keyword would be required instead of VAR in Pascal. 
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3.5.2 Calling Pascal from C—Function Call 


The example below demonstrates a C main module calling a Pascal func- 
tion, fact. This function returns the factorial of an integer value. 


mg Example 


/* C source file - calls Pascal function +/ 
/* Compile in MEDIUM or LARGE model +*/ 


extern int pascal fact (int); 
/* PASCAL keyword causes C to use BASIC/FORTRAN/Pascal 


calling and naming conventions * / 
/*x Integer parameter passed by value, the C default +«/ 


main () 
{ 
int x = 33 
int y = 4; 
printf("The factorial of x is 44d", fact (x)); 
printf("The factorial of y is %4d", fact(y)):; 
printf("The factorial of xty is %4d", fact (xty)); 
i; 
{ Pascal source code - factorial function. } 


module Pfun; 
function Fact (n : integer) : integer; 


{Integer parameters received by value, the Pascal default. } 


begin 
Fact := 1; 
while n > O do 
begin 
Fact := Fact * n> 
Th 4 ne. dg {Parameter n modified here. } 
end: 
end; 
end. 


Naming conventions: The pascal keyword directs C to call fact with 
the BASIC/FORTRAN/Pascal naming convention (as FACT). 


Calling conventions: The pascal keyword directs C to call fact with 
the BASIC/FORTRAN/Pascal calling convention. 


Parameter-passing methods: The Pascal function above should receive 
a parameter by value. Otherwise, the Pascal function will corrupt the 
parameter’s value in the calling module. Passing by value is the default 
method for both C and Pascal. 
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FORTRAN Calls to High-Level Languages 


Microsoft FORTRAN supports calls to routines written in Microsoft C and 
Pascal. Also, if the main program is in BASIC, then a FORTRAN routine 
can call a BASIC routine. This chapter describes the necessary syntax for 
calling other languages from FORTRAN, and then gives examples for each 
language. Only simple parameter lists are used in this chapter. 


For information on how to pass particular kinds of data, consult Part 
2, “Data Handling Reference.” Chapter 9 describes how to use the 
VARYING attribute with FORTRAN to pass a variable number of 


parameters. 


4.1 The FORTRAN Interface to Other 


Languages 


To call another language routine from within a FORTRAN function, first 
write an interface to the routine with the INTERFACE statement. This 
statement allows you to use special keywords (attributes) that affect how 
FORTRAN carries out calls. These keywords allow you to adjust naming 
conventions, calling conventions, and parameter-passing methods so that 
you can make routines from other languages compatible with FORTRAN. 


4.1.1 The INTERFACE Statement 


Here are the recommended rules for writing correct interfaces to routines 
from other languages: 


1. Write an INTERFACE statement for each routine you call. 


Write the interface toa FUNCTION if the routine returns a 
value, or toa SUBROUTINE if the routine does not return a 
value. The INTERFACE statement should precede any calls to 
the routine. 


2. Apply the C attribute to the routine if it is written in C (unless the 
C module is compiled with /Ge or is modified with the fortran or 
pascal keyword). 


The C attribute causes the routine to be called with the C naming 
and calling conventions. It also changes the default parameter- 
passing method for all parameters to pass by value. To apply the C 
attribute, type [C] immediately after the name of the routine. 


3. If the routine is called from Pascal, you may want to apply the 
PASCAL attribute to the routine; this keyword does not change 
calling or naming conventions, but changes the default parameter- 
passing method for all parameters to pass by value. 
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To apply the PASCAL attribute, type [PASCAL] immediately 


after the name of the routine. 


4. If the name of the routine is longer than six characters, use the 
ALIAS attribute. The use of ALIAS is explained in Section 4.1.2. 


5. Adjust parameter-passing methods by applying the VALUE, 
NEAR, FAR, and REFERENCE attributes to parameter 


declarations. 


The REFERENCE attribute can be useful because the C and 
PASCAL keywords automatically change the default parameter- 
passing method to passing by value. For any given parameter, 
REFERENCE changes the method back to passing by reference. 
(By default, FORTRAN passes by far reference unless you are 
using medium memory model which is available with FORTRAN, 
Versions 4.0 and later.) 


To apply an attribute to a parameter declaration, put the attribute 
in brackets, along with any other attributes that modify the same 
object, and place the attribute(s) and brackets immediately after 
the parameter. (Refer to the examples below.) 


6. Once the proper interface is set up, call the routine just as you 
would call any FORTRAN function or subroutine. 


m Examples 


In the examples below, the variables N, I, and J are not significant, 
except for their types and attributes. 


INTERFACE TO SUBROUTINE TEST [PASCAL] (N) 
INTEGER*2 N [NEAR, REFERENCE] 
END 


The first example declares the subroutine TEST with the PASCAL attri- 
bute. This subroutine takes one argument, N, which has both the NEAR 
and REFERENCE attributes. N is passed by near reference. 


INTERFACE TO FUNCTION REAL*8 CEFUN [C] (I,J) 
REAL+8 I [REFERENCE] 

REAL#8 J 

END 


The second example declares a C function, CEUN, which returns a value of 
type REAL#8. The argument I is passed by far reference because of the 
REFERENCE attribute; the argument J is passed by value because the 
C attribute changes the default. 
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4.1.2 Using ALIAS 
The ALIAS attribute is used with the following syntax 
ALIAS: ' aliasname' 


where aliasname is the name that FORTRAN will actually place in the 
object code whenever the declared routine is called. When you use this 
feature, alzasname is precisely what FORTRAN will place in the object 
code; therefore, if you are linking to a C routine, be sure to type a leading 
underscore (_) before the name. 


The ALIAS feature is necessary when the name of a routine is longer than 
6 characters. Without ALIAS, FORTRAN would place only the first 6 
characters into the object file, while the other language would place 7 or 8 
characters into the other object file (or up to 40 in the case of BASIC). 
This difference would prevent the linker from finding a match. 


@ Example 


INTERFACE TO PRINTNUM [C, ALIAS:'_printnum'] (N) 
INTEGER+2 N 
END 


In the example above, ALIAS is used because PRINTNUM is longer than 
six characters. Note that the leading underscore should be used only when 
linking to a routine that uses the C naming convention. 


4.2 Alternative FORTRAN Interface to C 


Instead of modifying the behavior of FORTRAN with the C attribute, you 
can modify the behavior of C by applying the pascal or fortran keyword 
to the function definition heading. (These two keywords are functionally 
equivalent). Or you can compile the C module with the /Ge option, which 
specifies that all C functions, calls, and public symbols use the 
BASIC/FORTRAN/Pascal conventions. 


For example, the following C function uses the BASIC/FORTRAN/Pascal 


conventions to receive an integer parameter: 


int fortran fun (n) 
int n> 


49 


Microsoft Mixed-Language Programming Guide 


4.3 FORTRAN Calls to BASIC 


Calls to BASIC from FORTRAN programs are not directly supported. No 
BASIC routine can be executed unless the main program is in BASIC, 
because a BASIC routine requires the environment to be initialized in a 
way that is unique to BASIC. No other language will perform this special 
initialization. 


However, it is possible for a program to start up in BASIC, call a FOR- 
TRAN function that does most of the work of the program, and then call 
BASIC subprograms and function procedures as needed. Figure 4.1 illus- 
trates how this can be done. 


Here are the recommended rules for calling BASIC from FORTRAN: 


1. Start up in a BASIC main module. You will need to use Quick- 
BASIC, Version 4.0 or later, and may want to use the DECLARE 
statement to write an interface to the principal FORTRAN rou- 
tine. (See Chapter 2, “BASIC Calls to High-Level Languages,” for 
more information.) 


2. Write an interface in FORTRAN for each BASIC routine you plan 
to call. Since BASIC and FORTRAN use the same basic calling 
convention, no special keyword is required to make FORTRAN 
compatible with BASIC. 


3. Make sure that all data are passed as a near pointer. BASIC can 
pass data in a variety of ways, but is unable to receive data in any 
form other than near reference. 


With near pointers, the program assumes that the data are in the 
default data segment. If you want to pass data that are not in the 
default data segment (this is only a consideration with large model 
programs), then first copy the data to a variable that is in the 
default data segment. 


m= Example 


The example below demonstrates a BASIC program which calls a FOR- 
TRAN subroutine. The FORTRAN subroutine then calls a BASIC func- 
tion that returns twice the number passed it, and a BASIC subprogram 
that prints two numbers. 
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' BASIC source 
t 
DEFINT A-Z 
DECLARE SUB Fprog () 
CALL Fprog 
END 
] 


FUNCTION Db1(N) STATIC 
Dbl = Nxe2 

END FUNCTION 

t 


SUB Printnum(A,B) STATIC 
PRINT "The first number is ":A 
PRINT "The second number is ":;B 
END SUB 


FORTRAN subroutine 
Calls a BASIC function that receives one integer, 
and a BASIC subprogram that takes two integers. 


aQqaaqaaan 


INTERFACE TO INTEGER+2 FUNCTION DBL (N) 
INTEGER*2 N [NEAR] 
END 


ALIAS attribute necessary because BASIC recognizes more 
than six characters of the name "Printnum" 


QAAaAN 


INTERFACE TO SUBROUTINE PRINTIN [ALIAS:'Printnum'] (N1, N2) 
INTEGER*2 Ni [NEAR] 

INTEGER+2 N2 [NEAR] 

END 


Parameters must be declared NEAR in the parameter 
declarations; BASIC receives ONLY 2~byte pointers 


M02AND 


SUBROUTINE FPROG 
INTEGER+2 DBL 

INTEGER+2 A,B 

A=5 

B= 6 

WRITE (*,+*) ‘Twice of 5 is ', DBL(A) 
CALL PRINTN (A, B) 

END 


In the example above, note that the NEAR attribute is used in the FOR- 
TRAN routines, so that near addresses will be passed to BASIC instead of 
far addresses. 
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(BASIC start-up} 


CALL Fsub 


ee SUBROUTINE FSUB 


(BASIC termination) 


SUB Btest STATIC 


END SUB 


Figure 4.1 FORTRAN Call to BASIC 


4.4 FORTRAN Calls to C 


Writing FORTRAN interfaces to C is fairly straightforward; however, if 
you are using Version 4.0 of FORTRAN, then linking requires some addi- 
tional steps, which are described in Chapter I. 


This section applies the steps outlined in Section 4.1 to two examples of 
FORTRAN-C programs. A brief analysis follows each example. 


4.4.1 Calling C from FORTRAN— 
No Return Value 


The example below demonstrates a FORTRAN main module calling a C 
function, maxparam. This function returns no value but adjusts the lower 
of two parameters to equal the higher argument. 
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# Example 


C FORTRAN SOURCE FILE - CALLS C FUNCTION, NO RETURN VALUE 
E 
INTERFACE TO SUBROUTINE MAXPARAM[C, ALIAS: '_maxparam'] (I,J) 
INTEGER+2 I [NEAR, REFERENCE] 
INTEGER*2 J [NEAR, REFERENCE] 
END 
c 
C CC ATTRIBUTE DIRECTS FORTRAN TO USE C CONVENTIONS 
C ALIAS NECESSARY BECAUSE 'MAXPARAM' LONGER THAN 6 CHARS. 
C EACH PARAMETER PASSED BY NEAR REFERENCE 
‘a 
INTEGER+2 I,J 
T=5 
J=7 
WRITE ‘(io0)) “1 = 7,0? oe. 3 
CALL MAXPARAM(I, J) 
WRITE (#,*) ‘I= ',I,'J=', J 
END 


/* C source file +/ 
/* Compile in MEDIUM or LARGE memory model +/ 
/* Maxparam declared VOID because no return value +/ 


void maxparam(pl, p2) 


int near *pl; /* Integer params received by near ref. «/ 
int near *p2; /* NEAR keyword not needed in MEDIUM model «/ 
if (*pl > *p2) 
*p2 = *pl; 
else 
*pl = *p2; 


i 


Naming conventions: By default, FORTRAN only places the first six 
characters of MAXPARAM into the object file, whereas C places all eight. 
This conflict is resolved with the ALIAS attribute: both modules place 
_maxparam (consistent with the C naming convention) into an object file. 


Calling conventions: The C attribute (in the INTERFACE statement) 
causes MAXPARAM to be called with the C calling convention, which 
pushes parameters in reverse order and specifies other lower-level 
differences. 


Parameter-passing methods: Since the function maxparam may alter 
the value of either parameter, both must be passed by reference. Near 
reference 1s implemented in FORTRAN with the NEAR and REFER- 
ENCE attributes, and in C by using near pointers. The REFERENCE 
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attribute is necessary in FORTRAN because the C keyword changes the 
default passing method to pass by value. 


Far reference could have been specified by leaving off the NEAR keyword 
from the FORTRAN parameter declarations. In that case, the C module 
would need to use far pointers. 


4.4.2 Calling C from FORTRAN— 
Function Call 


The example below demonstrates a FORTRAN main module calling a C 
function, fact. This function returns the factorial of an integer value. 


m Example 


C FORTRAN SOURCE FILE - CALLS C FUNCTION 
C 


INTERFACE TO INTEGER+2 FUNCTION FACT [C] (N) 
INTEGER«2 N 
END 


C ATTRIBUTE DIRECTS FORTRAN TO USE C CONVENTIONS 
PARAMETER PASSED BY VALUE, WHICH IS DEFAULT WHEN 
C ATTRIBUTE IS IN USE 


AQAAAA 


INTEGER*2 FACT 
INTEGER+2 I,J 

I = 3 

J= 4 

WRITE (*,%) ‘The factorial of I is ',FACT(TI) 
WRITE (*,*) ‘The factorial of J. is ',FACT(J) 
WRITE (+*,%) ‘The factorial of I+J is ',FACT(I+J) 
END 


/* C source file +/ 
/* Compile in MEDIUM or LARGE model +#/ 
/* Eactorial function, returning integer +*/ 


int fact (n) 


int n; /* Integer received by value, the C default +/ 
{ 
int result = 1; 
while (n) 
result *= n--; /* Parameter n modified here +/ 


return (result); 


t 


Naming conventions: The C attribute (in the INTERFACE state- 
ment) causes FACT to be called with the C naming convention (as _fact). 
Word length is not a concern; fact does not exceed six characters. 
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Calling conventions: The C attribute (in the INTERFACE statement) 
causes FACT to be called with the C calling convention, which pushes 
parameters in reverse order and specifies other lower-level differences. 


Parameter-passing methods: The C function above should receive the 
parameter by value. Otherwise, the function will corrupt the parameter’s 
value in the calling module. Passing by value is the default method for C; 
it is also the default method for FORTRAN whenever the C attribute is in 


use. 


4.55 FORTRAN Calls to Pascal 


Calling Pascal from FORTRAN 1s usually fairly simple, because the PAS- 
CAL attribute causes FORTRAN to use the Pascal default of passing 
data by value. 


This section applies the steps outlined in Section 4.1 to two examples of 
FORTRAN-Pascal programs. A brief analysis follows each example. 


4.5.1 Calling Pascal from FORTRAN— 
Procedure Call 


The example below demonstrates a FORTRAN main module calling a Pas- 
cal procedure, Maxparam. This procedure adjusts the lower of two 
parameters to equal the higher argument. 


m@ Example 


C FORTRAN SOURCE FILE - CALLS PASCAL PROCEDURE 
C 
INTERFACE TO SUBROUTINE MAXPARAM [ALIAS: 'MAXPARAM'] (I,J) 
INTEGER*2 I [NEAR] 
INTEGER*2 J [NEAR] 
END 


ALIAS NECESSARY BECAUSE "MAXPARAM' LONGER THAN 6 CHARS. 
EACH PARAMETER PASSED BY NEAR REFERENCE 


QOan 


INTEGER+2 I,J 
I=5 

J=7 

WRITE (*,4) ‘I = ',1I,' J 
CALL MAXPARAM (I,J) 

WRITE. (4,4). 4h = 2 oS 
END 


ll 
Cy 
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{ Pascal source code - Maxparam procedure. } 


module Psub; 
procedure Maxparam(var a:integer; var b:integer) ; 


{ Two integer parameters are received by near reference. } 
{ Near reference is specified with the VAR keyword. } 


begin 
if a > b then 
bi=a 
else 
as=b 
end: 
end. 


Naming conventions: By default, FORTRAN only places the first six 
characters of MAXPARAM into the object file, whereas Pascal places all 
eight. The ALIAS attribute resolves this conflict: both modules place 
MAXPARAM into an object file. 


Calling conventions: FORTRAN and Pascal use the same convention for 
calling. 


Parameter-passing methods: Since the procedure Maxparam may alter 
the value of either parameter, both must be passed by reference. Near ref- 
erence was implemented in FORTRAN with the NEAR attributes, and in 
Pascal with the VAR keyword. The PASCAL attribute is not used here 


because no parameter is being passed by value. 


Far reference could have been specified by leaving off the NEAR keyword 
from the FORTRAN parameter declarations. In that case, the Pascal mod- 
ule would use VARS instead of VAR. 


4.5.2 Calling Pascal from FORTRAN— 
Function Call 


The example below demonstrates a FORTRAN main module calling a Pas- 
cal function, Fact. This function returns the factorial of an integer value. 
# Example 

Cc FORTRAN SOURCE FILE - CALLS PASCAL FUNCTION 

C 


INTERFACE TO INTEGER*2 FUNCTION FACT [PASCAL] (N) 
INTEGER+#2 N 
END 
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C 
C PARAMETER PASSED BY VALUE, WHICH IS DEFAULT WHEN 
C PASCAL ATTRIBUTE IS IN USE 
C 
INTEGER*2 FACT 
INTEGER+2 I,J 
I = 3 
J=4 
WRITE (*,+*) 'The factorial of I is ',FACT(I) 
WRITE (*,%) ‘The factorial of J is ',FACT(J) 
WRITE (*,%*) ‘The factorial of I+tJ is ',FACT(I+J) 
END 
{ Pascal source code - factorial function. } 


module Pfun; 
function Fact (n : integer) : integer; 


{Integer parameters received by value, the Pascal default. } 


begin 
Fact ;:= 1: : 
while n > 0 do 
begin 
Fact := Fact * n: 
i. f= Ty = {Parameter n modified here.} 
end: 
end; 
end. 


Naming conventions: FORTRAN and Pascal use a similar naming con- 
vention. The ALIAS attribute is not necessary because the function name 
does not exceed six characters. 


Calling conventions: FORTRAN and Pascal use the same calling con- 
vention. 


Parameter-passing methods: The Pascal function above should receive 
the parameter by value. Otherwise, the function will corrupt the 
parameter’s value in the calling module. Passing by value is the default 
method for Pascal; it is also the default method for FORTRAN whenever 
the PASCAL attribute is in use. 
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Pascal Calls to High-Level Languages 


Microsoft Pascal supports calls to routines written in Microsoft FOR- 
TRAN and C. Also, if the main program is in BASIC, then a Pascal rou- 
tine can call a BASIC routine. This chapter describes the necessary syntax 
for calling these other languages, and then gives examples for each 
language. Only simple parameter lists are used in this chapter. 


For information on how to pass particular kinds of data, consult Part 2, 
“Data Handling Reference.” Chapter 9 describes how to use the VARY- 
ING attribute with Pascal to pass a varying number of parameters. 


5.1 The Pascal Interface to Other Languages 


You can provide an interface from Pascal to a routine in a different pro- 
gramming language. This interface is created by writing an extern func- 
tion or procedure declaration. This declaration informs Pascal that the 
routine is to be found in another module; furthermore, you can use special 
keywords with the declaration to affect how Pascal makes calls to the rou- 
tine. These keywords allow you to adjust naming conventions, calling con- 
ventions, and parameter-passing methods, so that the other language rou- 
tines will be compatible with Pascal. 


Here are the recommended steps for writing an extern declaration: 


1. Declare a function (for routines that return values) or a procedure 
(for routines that do not); all normal rules of Pascal syntax apply 
to the heading. Instead of writing a procedure body, however, sim- 
ply type the word extern, followed by a semicolon (;). 


The extern can be placed in the procedure declaration section of 
any Pascal function or procedure that needs to call the different 
language routine. 


2. If you are calling a C function, attach the C attribute to the 
declaration. To use this attribute, type C in brackets, at the very 
end of the function or procedure heading (immediately before the 
semicolon). 


This attribute directs Pascal to use the C naming and calling con- 
ventions. There is no similar keyword for FORTRAN or BASIC; 
they use the same naming and calling conventions used by Pascal. 


3. Decide how you want to pass each parameter. By default Pascal 
passes parameters by value. The VAR keyword, applied to indivi- 
dual parameters, specifies passing by near reference, and the 
VARS keyword specifies passing by far reference. 


4. Once the routine is properly declared, call it just as though it were 
a Pascal function or procedure. 
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m@ Examples 
procedure Cale(var i:integer; x:real) [C]; extern; 


In the example above, the C attribute directs Pascal to use the C calling 
and naming conventions. 


function Quadratic(a,b,c : integer) : real [C]; extern; 


In this example also, the C attribute directs Pascal to use the C calling 
and naming conventions. 


procedure Total (a,b,c : integer, var sum : integer); extern; 


The third example, by default, uses the BASIC/FORTRAN/Pascal stan- 
dard naming and calling conventions. 


5.2 Alternative Pascal Interface to C 


Instead of modifying the behavior of Pascal with the C attribute, you can 
modify the behavior of C by applying the pascal or fortran keyword to 
the function definition heading. (These two keywords are functionally 
equivalent.) You can also compile the C module with the /Ge option, 
which specifies that all C functions, calls, and public symbols use the 
BASIC ii FORTRAN/Pascal conventions. 


@ Example 


int pascal funl (n) 
bls glows o: 


In the example above, the C function uses the BASIC/FORTRAN/Pascal 
conventions to receive an integer parameter. 


5.3 Pascal Calls to BASIC 


Calls to BASIC from Pascal programs are not directly supported. No 
BASIC routine can be executed unless the main program is in BASIC 
because a BASIC routine requires the environment to be initialized in a 
unique way. No other language will perform this special initialization. 
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However, it is possible for a program to start up in BASIC, call a Pascal 
routine that does most of the work of the program, and then call BASIC 
subprograms and function procedures as needed. The following diagram 
illustrates how this can be done: 


(BASIC start-up) 


CALL Psub 
END 


ae PROCEDURE Psub; 
(BASIC termination) 


SUB Btest STATIC 


END SUB 


Figure 5.1 Pascal Call to BASIC 


Observe the following steps when calling BASIC from Pascal: 


1. Start up in a BASIC main module. You will need to use Quick- 
BASIC, Version 4.0 or later, and may want to use the DECLARE 
statement to write an interface to the principal Pascal routine. (See 
Chapter 2, “BASIC Calls to High-Level Languages,” for additional 


information.) 


2. Once in Pascal code, declare each BASIC routine you plan to call, 
in an extern procedure or function declaration. 


3. Make sure that all data are passed as a near pointer, by declaring 
each argument with VAR. BASIC can pass data in a variety of 
ways, but is unable to receive data in any form other than as a 
near pointer. 
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With near pointers, the program assumes that the data are in the 
default data segment. If you want to pass data that are not in the 
default data segment (this is only a consideration with far-heap 
allocation), then first copy the data to a variable that is in the 
default data segment. 


m Example 


The following example demonstrates a BASIC program which calls a Pas- 
cal procedure. The Pascal procedure then calls a BASIC function that 
returns twice the number passed it, and a BASIC subprogram that prints 
two numbers. | 


' BASIC source 
DEFINT A-Z 

DECLARE SUB Pprog () 
CALL Pprog 

END 


FUNCTION Db1(N) STATIC 
Dbl = Ne2 

END FUNCTION 

t 


SUB Printnum (A,B) STATIC 
PRINT "The first number is ";A 
PRINT "The second number is ";B 
END SUB 


{* Pascal procedure *} 
{* Calls a BASIC function and a BASIC subprogram *} 


module pproc; 
procedure Pprog(); 


function Dbl (var n:integer):integer; extern; 
procedure Printnum (var nl,n2:integer); extern; 
var a,b:integer; 


begin 
a, $=) 5% 
b := 6: 
writeln (‘Twice of 5 is ', Dbl (a)); 
Printnum (a,b); 
ena; 


end. 


In the example above, note that every argument in the external declara- 
tions must be declared VAR, since BASIC can only receive near pointers 
as parameters. 
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5.4 Pascal Calls to C 


This section applies the steps outlined in Section 5.1 to two examples of 
Pascal-C programs. A brief analysis follows each example. 


5.4.1 Calling C from Pascal—No Return Value 


The example below demonstrates a Pascal main module calling a C func- 
tion, maxparam. This function returns no value, but adjusts the lower of 
two arguments to equal the higher. 


mw Example 
{ Pascal source file - calls C function, no return value } 


program Pcsub (input, output); 
procedure Maxparam (var i,j : integer) [C]; extern; 


{ C attribute directs Pascal to use C conventions. } 
{ VAR indicates each parameter passed by near reference. } 


var 
a, b : integer; 
begin 
a:= 5; 
b 3= 77> 
writeln('a =a; Do = *36)3 
Maxparam (a,b) ; 
writeln('a = ',a,'b = ',b); 
end. 


/* €C source file +«/ 
/* Compile in MEDIUM or LARGE memory model «/ 
/* Maxparam declared VOID because no return value +/ 


void maxparam(pl, p2) 


int near *#pl? /* Integer params received by near ref. +/ 
int near *p2; /* NEAR keyword not needed in MEDIUM model +/ 
if (*pl > *p2) 
*p2 = xpl; 
else 
tpl = x*p2; 


J 


Naming conventions: The C attribute causes Maxparam to be called 
with the C naming convention (as __maxparam). 
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Calling conventions: The C attribute causes Maxparam to be called 
with the C calling convention, which pushes parameters 1p reverse order. 


Parameter-passing methods: Since the subprogram Maxparam may 
alter the value of either parameter, both arguments must be passed by 
reference. In this case, near reference was chosen; this method is specified 
in Pascal with the VAR keyword, and in C by using near pointers. 


Far reference could have been specified by using VARS instead of VAR; 
in that case, the C parameter declarations would use far pointers. 


5.4.2 Calling C from Pascal—F unction Call 


The example below demonstrates a Pascal main module calling a C func- 
tion, fact. This function returns the factorial of an integer value. 


= Example 


{ Pascal source file - calls C function } 


program Pcfun (input, output); 
function Fact (n : integer) [C]; extern; 


{ C attribute directs Pascal to use C conventions. } 
{ Parameter passed by value, the default method. } 


var 
a, b : integer; 
begin 
ai= 3; 
b 3= 4; 
writeln(’The factorial of a is ', Fact(a)); 
writeln('The factorial of b is ', Fact(b)); 
writeln('The factorial of atb is ', Fact(atb)); 
end. 


/* C source file *«/ 
/* Compile in MEDIUM or LARGE model +*/ 
/* Factorial function, returning integer +*/ 


int fact (n) 


inton: /* Integer received by value, the C default +#/ 
{ 

int result = 1; 

while (n) 


result «= n--; /* Parameter n modified here */ 
return (result); 
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Naming conventions: The C attribute causes Fact to be called with the 


C naming convention (as _ fact). 


Calling conventions: The C attribute causes Fact to be called with the 
C calling convention, which pushes parameters in reverse order, and spec- 


ifies other low-level differences. 


Parameter-passing methods: The C function should receive the integer 


parameter by value. Otherwise, the function will corrupt the value of the 
parameter in the calling routine. Passing by value is the default method 
for both Pascal and C. 


5.5 Pascal Calls to FORTRAN 


This section applies the steps outlined in Section 5.1 to two examples of 
Pascal-FORTRAN programs. A brief analysis follows each example. 


5.5.1 Calling FORTRAN from Pascal— 
Subroutine Call 


The example below demonstrates a Pascal main module calling a FOR- 
TRAN subroutine, MAXPARAM. This subroutine adjusts the lower of two 
arguments to equal the higher. 


# Example 


{ Pascal source file - calls FORTRAN subroutine } 


program Pfsub (output); 
procedure Maxpar (var i,j : integer) ; extern; 


{ Name must not exceed six characters. } 
{ VAR indicates each parameter passed by near reference. } 


var 
a, b : integer: 
begin 
a:= 53 
b := 7: 
writeln('a = ',a,'b = ',b); 
Maxpar (a,b); 
writeln('a = ',a,'b = ',b); 
end. 
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C FORTRAN source file, subroutine MAXPARAM 
C 


SUBROUTINE MAXPARAM (I, J) 
INTEGER*2 I [NEAR] 
INTEGER+2 J [NEAR] 


C 
C I and J received by near reference, because of NEAR attribute 
C 
IF (I .GT. J) THEN 
J= TI 
ELSE 
lT=J 
ENDIF 
END 


Naming conventions: By default, Pascal places all eight characters of 
Maxparam into the object file, whereas FORTRAN places only the first 
six. This conflict is resolved by shortening the name of the Pascal routine 
to six characters. 


Calling conventions: Pascal and FORTRAN use the same calling con- 
vention. 


Parameter-passing methods: Since the subprogram Maxparam may 
alter the value of either parameter, both arguments must be passed by 
reference. In this case, near reference was chosen; this method is specified 
in Pascal with the VAR keyword, and in FORTRAN by applying the 
NEAR attribute to each parameter declaration. 


Far reference could have been chosen by using VARS instead of VAR. In 
that case, the NEAR attribute would not be used in the FORTRAN 


parameter declarations. 


5.5.2 Calling FORTRAN from Pascal— 
Function Call 


The example below demonstrates a Pascal main module calling a FOR- 
TRAN function, FACT. This function returns the factorial of an integer 
value. 
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# Example 


{ Pascal source file - calls FORTRAN function } 


program Pffun (output); 
function Fact (n : integer); extern; 


{ Parameter passed by value, the default method. } 


var 
a, b : integer; 
begin 
ai= 33 
b 3:= 4; 
writeln('The factorial of a is ', Fact(a)); 
writeln('The factorial of b is ', Fact(b)); 
writeln('The factorial of atb is ', Fact(atb)); 
end. 


@ FORTRAN source file - factorial function 
C 


INTEGER*2 FUNCTION FACT (N) 
INTEGER+2 N [VALUE] 


C 
C N is received by value, because of VALUE attribute 
C 
INTEGER*2 I 
FACT = 1 
DO 100 I =1, N 
FACT = FACT « I 
100 CONTINUE 
RETURN 
END 


Naming conventions: There are no conflicts with naming conventions, 
because the function name (FACT) does not exceed six characters. 


Calling conventions: Pascal and FORTRAN use the same convention for 
calling. 


Parameter-passing methods: When passing a parameter that should 
not be changed, it is generally safest to pass the parameter by value. Pass- 
ing by value is the default method in Pascal, and is specified in FORTRAN 
by applying the VALUE attribute to a parameter declaration. 
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Assembly-to-High-Level Interface 


With the Microsoft Macro Assembler you can write assembly modules that 
can be linked to modules developed with Microsoft BASIC, C, Pascal, or 
FORTRAN. This chapter first outlines the recommended programming 
guidelines for writing assembly routines compatible with Microsoft high- 
level languages; it then gives examples specific to each language. 


Writing assembly routines for Microsoft high-level languages is easiest 
when you use the simplified segment directives provided with the Macro 
Assembler, Version 5.0. In general, this manual assumes that you have 
Version 5.0. For information on writing assembly-language interfaces 
without the simplified segment directives, turn to Section 6.7 in order to 
look up SEGMENT, GROUP, and ASSUME statements. 


6.1 Writing the Assembly Procedure 


The Microsoft BASIC, C, FORTRAN, and Pascal compilers use roughly 
the same interface for procedure calls. This section describes the interface, 
so that you can call assembly procedures using essentially the same 
methods as Microsoft compiler-generated code. Procedures written with 
these methods can be called recursively and can be effectively used with 
the Stack Trace feature of the Microsoft CodeViewe debugger. 


The standard assembly-interface method consists of these steps: 


e Setting up the procedure 

e Entering the procedure 

e Allocating local data (optional) 
e Preserving register values 

e Accessing parameters 

e Returning a value (optional) 


e Exiting the procedure 


Sections 6.1.1-6.1.7 describe each of these steps. 


6.1.1 Setting Up the Procedure 


The linker cannot combine the assembly procedure with the calling pro- 
gram unless compatible segments are used and unless the procedure itself 
is declared properly. The following points may be helpful: 


1. Use the MODEL directive at the beginning of the source file, if 


you have Version 5.0 of the Macro Assembler; this directive 
automatically causes the appropriate kind of returns to be 
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generated (NEAR for small or compact model, FAR otherwise). 
Modules called from Pascal should be declared as MODEL 
LARGE; modules called from BASIC should be MODEL 
MEDIUM. If you have a version of the assembler previous to 5.0, 
declare the procedure FAR (or NEAR if the calling program is 
small- or compact-model C). 


2. If you have Version 5.0 or later of the Microsoft Macro Assembler, 
use the simplified segment directives .CODE to declare the code 
segment and .DATA to declare the data segment. (Having a code 
segment is sufficient if you do not have data declarations.) If you 
are using an earlier version of the assembler, look up SEGMENT, 
GROUP, and ASSUME directives in Section 6.7, “The Microsoft 
Segment Model.” 


3. The procedure label must be declared public with the PUBLIC 
directive. This declaration makes the procedure available to be 
called by other modules. Also, any data you want to make public 
to other modules must be declared as PUBLIC. 


4. Global data or procedures accessed by the routine must be declared 
EXTRN. The safest way to use EX TRN is to place the directive 
outside of any segment definition (however, near data should gen- 

_ erally go inside the data segment). 


6.1.2 Entering the Procedure 
Two instructions begin the procedure: 


push bp 
mov bp, sp 


This sequence establishes BP as the “framepointer.” The framepointer is 
used to access parameters and local data, which are located on the stack. 
SP cannot be used for this purpose because it is not an index or base regis- 
ter. Also, the value of SP may change as more data are pushed onto the 
stack. However, the value of the base register BP will remain constant 
throughout the procedure, so that each parameter can be addressed as a 
fixed displacement off of BP. 


The instruction sequence above first saves the value of BP, since it will be 
needed by the calling procedure as soon as the current procedure ter- 
minates. Then BP is loaded with the value of SP in order to capture the 
value of the stack pointer at the time of entry to the procedure. 
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6.1.3 Allocating Local Data (Optional) 


An assembly procedure can use the same technique for implementing local 
data that is used by high-level languages. To set up local data space, sim- 
ly decrease the contents of SP in the third instruction of the procedure. 
To ensure correct execution, you should always increase or decrease SP 
by an even amount.) Decreasing SP reserves space on the stack for the 

local data. The space must be restored at the end of the procedure. 


push bp 
mov bp, sp 
sub Sp, space 


In the text above, space is the total size in bytes of the local data. Local 
variables are then accessed as fixed, negative displacements off of BP. 


m Example 


push bp 

mov bp, sp 

sub sp, 4 

mov WORD PTR [bp-2],0 
mov WORD PTR [bp-4],0 


The example above uses two local variables, each of which is two bytes in 
size. SP is decreased by 4, since there are four bytes total of local data. 
Later, each of the variables is initialized to 0. These variables are never 
formally declared with any assembler directive; the programmer must keep 
track of them manually. 


Local variables are also called dynamic, stack, or automatic variables. 


6.1.4 Preserving Register Values 


A procedure called from any of the Microsoft high-level languages should 
preserve the values of SI, DI, SS, and DS (in addition to BP, which is 
already saved). Therefore, push any of these register values that the pro- 
cedure alters. If the procedure does not change the value of any of these 
registers, then the registers do not need to be pushed. 
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The recommended method (used by the high-level languages) is to save 
registers after the framepointer is set and local data (if any) are allocated. 


push bp 3 Save old framepointer 

mov bp, sp ; Establish current framepointer 
sub sp,4 ; Allocate local data space 
push si ; Save SI and DI 


push adi 


In the example above, DI and SI (in that order) must be popped before the 
end of the procedure. 


6.1.5 Accessing Parameters 


Once you have established the procedure’s framepointer, allocated local 
data space (if desired), and pushed any registers that need to be preserved, 
you can write the main body of the procedure. In order to write instruc- 
tions that can access parameters, consider the general picture of the stack 
frame after a procedure call as illustrated in Figure 6.1. 


The stack frame for the procedure is established by the following sequence 
of events: 


1. The calling program pushes each of the parameters on the stack, 
after which SP points to the last parameter pushed. 


2. The calling program issues a CALL instruction, which causes the 
return address (the place in the calling program to which control 
will ultimately return) to be placed on the stack. This address may 
be either two bytes long (for near calls) or four bytes long (for far 
calls). SP now points to this address. 


3. The first instruction of the called procedure saves the old value of 
BP, with the instruction push bp. SP now points to the saved 
copy of BP. 


4. BP is used to capture the current value of SP, with the instruction 
mov bp,sp. BP therefore now points to the old value of BP. 


5. Whereas BP remains constant throughout the procedure, SP may 
be decreased to provide room on the stack, for local data or saved 
registers. 


In general, the displacement (off of BP) for a parameter X is equal to: 


2+ size of return address 
+ total size of parameters between X and BP 
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For example, consider a FAR procedure that has received one parameter, 
a two-byte address. The displacement of the parameter would be: 


Argument’s displacement ize of return address 


s 
4 


II 
On bh 


il 


The argument can thus be loaded into BX with the following instruction: 
mov bx, [bpt+6] 


Once you determine the displacement of each parameter, you may want to 
use string equates or structures so that the parameter can be referenced 
with a single identifier name in your assembly source code. For example, 
the parameter above at BP+6 can be conveniently accessed if you put the 
following statement at the beginning of the assembly source file: 


Argl EQU [bp+6] 


You could then refer to this parameter as Argl in any instruction. Use of 
this feature is optional. 


Parameter _ 


Local data space | | 


: 


| 
j 
Ea 
ry 
2 
: 
‘ 
> 
f 
f 
: 


Saved Dl 


Figure 6.1 The Stack Frame 
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Note 


Microsoft high-level languages always push segment addresses before 
pushing offset address. Furthermore, when pushing arguments larger 
than two bytes, high-order words are always pushed before low-order 
words. 


This standard for pushing segment addresses before pushing offset 
addresses facilitates the use of the LES instruction, as demonstrated 
in Section 6.4, “Calls from FORTRAN.” 


6.1.6 Returning a Value (Optional) 
Microsoft BASIC, C, FORTRAN, and Pascal share similar conventions for 


receiving return values. The conventions are the same when the data type 
to be returned is simple (that is, not an array or structured type) and is no 
more than four bytes long. This includes all NEAR and FAR address 
types (in other words, all pointers and all parameters passed by reference). 


Data size Returned in register 

1 byte AL 

2 bytes AX 

4 bytes High-order portion (or segment address) in DX; 


low-order portion (or offset address) in AX 


When the return value is larger than four bytes, a procedure called by C 
must allocate space for the return value and then place its address in 
DX:AX. A convenient way to create space for the return value is to sim- 
ply declare it in a data segment. 


If your assembly procedure is called by BASIC, FORTRAN or Pascal, then 
it must use a special convention in order to return floating-point values, 
records, user-defined types and arrays, and values larger than four bytes. 
This convention is presented below. 


m BASIC/FORTRAN/Pascal Long Return Values 
In order to create an interface for long return values, BASIC, FORTRAN 


at Pascal modules take the following actions before they call your pro- 
cedure: 
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1. First they create space, somewhere in the stack segment, to hold 
the actual return value. 


2. When the call to your procedure is made, an extra parameter is 
passed; this parameter contains the offset address of the actual 
return value. This parameter is placed immediately above the 
return address. (In other words, this parameter is the last one 
pushed.) 


3. The segment address of the return value is contained in both SS 
and DS. 


The extra parameter (which contains the offset address of the return 
value) is always located at BP+6. Furthermore, its presence automati- 
cally increases the displacement of all other parameters by two, as shown 
in the following comparison: 


a ee 


Parameter 


Return address 
(4 bytes) 


Saved BP 


| : 
Bie ae 


Figure 6.2 BASIC/FORTRAN/Pascal Long Return Values 


Your assembly procedure will successfully return a long value if you follow 
these steps: | 


1. Put the data for the return value at the location pointed to by the 
return value offset. 


2. Copy the return-value offset (located at BP+6) to AX, and copy 
SS to DX. This is necessary because the calling module expects 
DX:AX to point to the return value. 


3. Exit the procedure as described in the next section. 
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6.1.7 Exiting the Procedure 


Several steps may be involved in terminating the procedure: 


1. 


If any of the registers SS, DS, SI, or DI have been saved, these 
must be popped off the stack in the reverse order that they were 
saved. 


If local data space was allocated at the beginning of the procedure, 
SP must be restored with the instruction mov sp, bp. 


Restore BP with pop bp. This step is always necessary. 


Finally, return to the calling program with ret. If the BASIC, 
FORTRAN, or Pascal calling convention is in use, then use the 
ret nform of the instruction to adjust the stack with respect to 
the parameters that were pushed by the caller. (If the procedure is 
called by a C module, then the calling module will perform this 
adjustment. ) 


m Examples 


pop bp 
ret 


The example above shows the simplest possible exit sequence. No registers 
were saved, no local data space was allocated, and the © calling conven- 
tion is in use. 


pop di : Pop saved regs 
pop si 
MOv sp, bp Remove local data space 


pop bp ; Restore old framepointer 
ret 6 : Exit, and restore 6 byte of args 


The example above shows an exit sequence for a procedure that has previ- 
ously saved SI and DI, allocated local data space, and uses a non-C calling 
convention. The procedure must therefore use ret 6 to restore the six 
bytes of parameters on the stack. 
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6.2 Calls from BASIC 


A BASIC program can call an assembly procedure in another source file 
with the use of the CALL, CALLS, or DECLARE statement. In addi- 
tion to the steps outlined in Section 6.1, “Writing the Assembly Pro- 
cedure,” the following guidelines may be helpful: 


1. Declare procedures called from BASIC as FAR. 


2. Observe the BASIC calling convention. 


a. Upon exit, the procedure must reset SP to the value it had 
before the parameters were placed on the stack. This is accom- 
plished with the instruction ret size, where size is the total size 
in bytes of all the parameters. 


b. Parameters are placed on the stack in the same order in which 
they appear in the BASIC source code. The first parameter will 
be highest in memory (because it is also the first parameter to 
be placed on the stack, and the stack grows downward). 


c. By default, BASIC parameters are passed by reference as two- 
byte addresses. 


3. Observe the BASIC naming convention. 


BASIC outputs symbolic names in uppercase characters, which is 
also the default behavior of the assembler. BASIC recognizes up to 
40 characters of a name, whereas the assembler recognizes only the 
first 31, but this should rarely create a problem. 


In the following example program, QuickBASIC 4.0 calls an assembly pro- 
cedure that calculates “A x 28,” where A and B are the first and second 
parameters, respectively. The calculation is performed by shifting the bits 
in A to the left, B times. (Note: with earlier versions of BASIC, you need 
to rewrite the example so that it calls a subprogram, not a function.) 


DEFINT A-Z 

PRINT "3 times 2 to the power of 5 is "; 
PRINT Power2 (3,5) 

END 
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To understand how to write the assembly procedure, consider how the 


parameters are placed on the stack: 


Return address 
(4 bytes) 


Figure 6.3 BASIC Stack Frame 


The return address is four bytes long because procedures called from 
BASIC must be FAR. Arg 1 (parameter 1) is higher in memory than Arg 2 
because BASIC pushes arguments (parameters) in the same order in which 
they appear. Also, each argument is passed as a two-byte offset address, 


the BASIC default. 


The assembly procedure can be written as follows: 


»~MODEL MEDIUM 


. CODE 
PUBLIC Power2 


Power2 PROC 


push bp 
mov bp, sp 
mov bx, [bpt+8] 
mov ax, [bx] 
mov bx, [bp+6] 
mov cx, [bx] 
shl ax,cl 
pop bp 
ret 4 

Power2 ENDP 
END 
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Entry sequence - saved old BP 
Set stack framepointer 


Load Argl into 
AX 
Load Arg2Z into 
CX 
AX = AX * (2 to power of CX) 
Leave return value in AX 


Exit sequence - restore old BP 
Return, and restore 4 bytes 
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Note that each parameter must be loaded in a two-step process because 
the address of each is passed rather than the value. Also, note that the 
stack is restored with the instruction ret 4 since the total size of the 
parameters is four bytes. 


6.3 Calls from C 


A C program can call an assembly procedure in another module, just as it 
would call a C function. In addition to the steps outlined in Section 6.1, 
“Writing the Assembly Procedure,” the following guidelines may prove 
helpful: 


1. Declare procedures called from C as FAR if the C module is com- 
piled in large, huge, or medium model, and NEAR if the C module 
is compiled in small or compact model (although the near and far 
keywords can override these defaults). The correct declaration for 
the procedure 1s made implicitly when you use the .MODEL direc- 
tive available in the Microsoft Macro Assembler, Version 5.0. 


2. Observe the C calling convention. 


a. Return with a simple ret instruction. Do not restore the stack 
with ret szze, since the calling C routine will restore the stack 
itself, as soon as it resumes control. 


b. Parameters are placed on the stack in the reverse order that 
they appear in the C source code. The first parameter will be 
lowest in memory (because it is the last parameter to placed on 
the stack, and the stack grows downward). 


c. By default, C parameters are passed by value, except for 
arrays, which are passed by reference. 


3. Observe the C naming convention. 


Include an underscore in front of any name which will be shared 
publicly with C. C recognizes only the first eight characters of any 
name, so do not make names shared with C longer than eight char- 
acters. Also, if you plan to link with the /NOIGNORECASE 
option, remember that C is case sensitive and does not convert 
names to uppercase. Assemble with the /MX option to prevent 
MASM from converting names to uppercase. 


In the following example program, C calls an assembly procedure that cal- 
culates “A x 28,” where A and B are the first and second parameters, 
respectively. The calculation is performed by shifting the bits in A to the 
left, B times. 
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The C program uses an extern declaration to create an interface with the 
assembly procedure. No special keywords are required because the assem- 
bly procedure will use the C calling convention. 


extern int power2(int, int); 


main () 


{ 
} 


To understand how to write the assembly procedure, consider how the 
parameters are placed on the stack, as illustrated in Figure 6.4. 


printf("3 times 2 to the power of 5 is ¥d\n", power2(3,5)); 


Figure 6.4 C Stack Frame 


The return address is two bytes long, assuming that the C module is com- 
piled in small or compact model. If the C module is compiled in large, 
huge, or medium model, then the addresses of Arg 1 and Arg 2 are each 
increased by two, to BP+6 and BP+8, respectively, because the return 
address will be four bytes long. 


Arg 1 (parameter 1) is lower in memory than Arg 2, because C pushes 
arguments in the reverse order that they appear. Each argument is passed 
by value. 
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The assembly procedure can be written as follows: 


».MODEL SMALL 
» CODE 

PUBLIC _power2 
_power2 PROC 


push bp ; Entry sequence - save old BP 
mov bp, sp ; Set stack framepointer 
mov ax, [opt+4] ; Load Argl into AX 


mov cx, [bpt+6] ; Load Arg2 into CX 


shl ax,cl ; AX = AX * (2 to power of CX) 
; Leave return value in AX 
pop bp ; Exit sequence - restore old BP 
ret ; Return 
_power2 ENDP 
END 


The example above assumes that the C module is compiled in small model. 
The parameter offsets and the .MODEL directive will change for different 
models. 


Note that ret without a size variable is used, since the caller will adjust 
the stack upon return from the call. 


6.4 Calls from FORTRAN 


A FORTRAN program can call an external assembly procedure with the 
use of the INTERFACE statement. However, the INTERFACE state- 
ment is not strictly necessary unless you intend to change one of the FOR- 
TRAN defaults. In addition to the steps outlined in Section 6.1, “Writing 
the Assembly Procedure,” the following guidelines may be helpful: 


1. Declare procedures called from FORTRAN as FAR. 


2. Observe the FORTRAN calling convention. 


a. Upon exit, the procedure must reset SP to the value it had 
before the arguments were placed on the stack. This is accom- 
plished with the instruction ret size, where size is the total size 
of all the parameters. 
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b. Arguments are placed on the stack in the same order in which 
they appear in the FORTRAN source code. The first parameter 
will be highest in memory (because it is also the first parameter 
to be placed on the stack, and the stack grows downward). 


c. By default, FORTRAN parameters are passed by reference as 
far addresses if the FORTRAN module is compiled in large or 
huge memory model, and as near addresses if the FORTRAN 
module is compiled in medium model. Versions of FORTRAN 
prior to Version 4.0 are always large model. 


3. Observe the FORTRAN naming convention. 


FORTRAN only recognizes the first 6 characters of any name, 
while the assembler recognizes the first 31. Names shared publicly 
with FORTRAN should not be longer than 6 characters, unless the 
FORTRAN module is using the ALIAS feature. 


In the following example, FORTRAN calls an assembly procedure that cal- 
culates “A x 2B.” where A and B are the first and second parameters, 
respectively. This is done by shifting the bits in A to the left, B times. 


The FORTRAN module uses the INTERFACE statement, which is 
described in Section 4.1, “The FORTRAN Interface to Other Languages.” 


INTERFACE TO INTEGER*2 POWER2 (A,B) 
INTEGER+2 A,B 
END 


INTEGER*2 A,B 

A = 3 

B= 5 

WRITE (*,*) '3 times 2 to the power of 5 is ',POWER2 (A,B) 
END 


To understand how to write the assembly procedure, consider how the 
parameters are placed on the stack, as illustrated in Figure 6.5. 


Figure 6.5 assumes large-model FORTRAN. If you compile the FORTRAN 
module in medium model, then each argument will be passed as a two- 
byte, not four-byte address. The return address is four bytes long because 
procedures called from FORTRAN must always be FAR. 


Arg 1 (parameter 1) is higher in memory than Arg 2 because FORTRAN 
pushes arguments (parameters) in the same order that they appear. 
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Arg 1 segment 


Arg 1 offset 


Arg 2 segment 


Arg 2 offset 


Return address 


Saved BP 


Figure 6.5 FORTRAN Stack Frame 


The assembly procedure can be written as follows: 


»-MODEL LARCE 


- CODE 


Power 2 


Power2 


PUBLIC Power 2 


PROC 
push 
mov 


les 
mov 
les 
mov 


shl 


pop 
ret 
ENDP 


END 


bp 
bp, sp 


bx, [bp+10] 
ax,es: [bx] 
bx, [bp+6] 
cx,es: [bx] 
ax,cl 


bp 
8 


we Se 


“es Se Se %e Se Se 


~“e “se 


Entry sequence - save old BP 
Set stack framepointer 


Load Argl into 
AX 
Load ArgZ into 
CX 
AX = AX * (2 to power of CX) 
Leave return value in AX 


Exit sequence - restore old BP 
Return and restore 8 bytes 
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In the example above, each argument must be loaded using the four-byte 
address that was pushed onto the stack. The procedure loads four-byte 
addresses with the LES instruction, which loads the destination operand 
(in this case, BX) with the source operand, and also loads ES with the 
object two bytes higher in memory. Thus, the instruction 


les bx, [ppt10] 


loads BX with the value at BP+10 (an offset address), and ES with the 
value at BP+12 (a segment address), which is necessary to set up the next 
instruction. | 


Upon exit, the stack is restored with the instruction ret 8, since the total 
size of parameters pushed onto the stack is eight. 


6.5 Calls from Pascal 


A Pascal program can call an assembly procedure in another module just 
as it would call a Pascal routine. In addition to the steps outlined in Sec- 
tion 6.1, “Writing the Assembly Procedure,” the following guidelines may 
be helpful: 


1. Declare procedures called from Pascal as FAR. This is taken care 
of for you automatically if you use the MODEL directive available 
oS the Microsoft Macro Assembler, Version 5.0 or later; specify 
LARGE. 


2. Observe the Pascal calling convention. 


a. Upon exit, the procedure must reset SP to the value it had 
before the parameters were placed on the stack. The procedure 
resets SP with the instruction ret size, where size is the total 
size of all the parameters pushed on the stack. 


b. Parameters are placed on the stack in the same order in which 
they appear in the Pascal source code. The first parameter will 
be highest in memory (because it is also the first parameter to 
be placed on the stack, and the stack grows downward. } 


c. By default, Pascal parameters are passed by value. 


3. Observe the Pascal naming convention. 
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Pascal only recognizes the first 8 characters of any name, while the 
assembler recognizes the first 31. Names shared publicly with Pas- 
cal should not be longer than 8 characters. 


In the following example program, Pascal calls an assembly procedure that 
calculates “A x 28,” where A and B are the first and second parameters, 
respectively. The calculation is performed by shifting the bits in A to the 


left, B times. 


The Pascal module uses an extern declaration in its interface with the 
assembly procedure. No special keywords are required, because the assem- 
bly procedure will use the Pascal calling convention. 


program Asmtest (input, output); 
function Power2(a,b:integer) :integer; extern; 
begin 
writeln('3 times 2 to the power of 5 is ',Power2(3,5)); 
end. 


To understand how to write the assembly procedure, consider how the 
parameters are placed on the stack, as illustrated in Figure 6.6. 


Return address 
(4 bytes) 


Figure 6.6 Pascal Stack Frame 


Arg 1 (parameter 1) is higher in memory than Arg 2 because Pascal pushes 
arguments in the same order that they appear. Each argument is passed 
by value. 
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The assembly procedure can be written as follows: 


»~MODEL LARGE 
.» CODE 

PUBLIC Power2 
Power2 PROC 


push bp > Entry sequence - save old BP 

mov bp, sp > Set stack framepointer 

mov ax, [bp+8] : Load Argl into AX 

mov cx, [bpt6] > Load Arg2 into CX 

shl ax,cl > AX = AX * (2 to power of CX) 

> Leave return value in AX 

pop bp > Exit sequence - restore old BP 

ret 4. : Return and restore 4 bytes 
Power2 ENDP 

END 


The AX and CX registers can be loaded directly because the parameters — 
were passed by value. Note that the ret 4 instruction is necessary to 
clear the stack of the four bytes of parameters. 


6.6 Calling High-Level Languages 
from Assembly 


High-level language routines assume that certain initialization code has 
previously been executed; you can ensure that the proper initialization is 
performed by starting in a high-level language module, and then calling an 
assembly procedure. The assembly procedure can then call high-level 
language routines as needed, as shown in Figure 6.7. 


To execute an assembly call to a high-level language, you need to observe 
the following guidelines: 


1. Push each parameter onto the stack, observing the calling conven- 
tion of the high-level language. Constants such as offset addresses 
must first be loaded into a register before being pushed. 


2. With long parameters, always push the segment or high-order por- 
tion of the parameter first, regardless of the calling convention. 


3. Execute a call. The call must be far unless the high-level language 
routine is small model. 
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4. If the routine used the C calling convention, then immediately 
after the call you must clear the stack of parameters with the 
instruction 


add sp, size 


where size is the total size in bytes of all parameters that were 
pushed. 


(C start-up) 


main(){ 
asub(); 


PROC asub 


(C termination) 


Call <arvest 


ret 
ENDP asub 


Figure 6.7 Assembly Call to C 


6.7 The Microsoft Segment Model 


If you use the simplified segment directives by themselves, you do not need 
to know the names assigned for each segment. However, versions of the 
Macro Assembler prior to 5.0 do not support these directives. With older 
versions of the assembler, you should use the SEGMENT, GROUP, 
ASSUME, and ENDS directives equivalent to the simplified segment 


directives. 
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Table 6.1 shows the default segment names created by each directive. Use 
of these segments ensures compatibility with Microsoft languages and will 
help you to access public symbols. This table is followed by a list of three 
steps, illustrating how to make the actual declarations, and an example 


program. 


Table 6.1 


Default Segments and Types 
for Standard Memory Models 


Model 


Small 


Medium 


Compact 


Large 


92 


Directive 


CODE 
DATA 
-CONST 
DATA? 
STACK 


CODE 
DATA 
CONST 
DATA? 
STACK 


CODE 
-FARDATA 
-FARDATA? 
DATA 
CONST 
DATA? 
STACK 


-CODE 
FARDATA 
FARDATA? 
DATA 
CONST 
‘DATA? 
STACK 


Name 


_TEXT 
~DATA. 
CONST 
BSS 
STACK 


name_TEXT 


DATA 
CONST 
_BSS 

STACK 


_~TEXT 


FAR_DATA 


FAR_BSS 
_DATA 
CONST 
_BSS 
STACK 


name_TEXT 
FAR_DATA 


FAR_BSS 
DATA 
CONST 
_BSS 
STACK 


Align 


WORD 
WORD 
WORD 
WORD 
PARA 


WORD 
WORD 
WORD 
WORD 
PARA 


WORD 
PARA 
PARA. 
WORD 
WORD 
WORD 
PARA 


WORD 
PARA 
PARA 
WORD 
WORD 
WORD 
PARA 


Combine 


PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
STACK 


PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
STACK 


PUBLIC 
private 

private 

PUBLIC 
PUBLIC 
PUBLIC 
STACK 


PUBLIC 
private 

private 

PUBLIC 
PUBLIC 
PUBLIC 
STACK 


Class 


*CODE’ 
‘DATA’ 
‘CONST’ 
"BS S ; 
‘STACK’ 


*CODE’ 
*?DATA’ 
*>CONST”’ 
BSS? 
STACK’ 


*>CODE’ 


-FAR_DATA’ 


"FAR_BSS’ 
*DATA’ 
°>CONST? 
"BSS? 
STACK’ 


*>CODE’ 


"FAR_DATA’ 


"FAR_BSS’ 
"DATA’ 
*>CONST?’ 
"BSS? 
STACK’ 


Group 


DGROUP 
DGROUP 
DGROUP 
DGROUP 


DGROUP 
DGROUP 
DGROUP 
DGROUP 


DGROUP 
DGROUP 
DGROUP 
DGROUP 


DGROUP 
DGROUP 
DGROUP 
DGROUP 
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The directives in Table 6.1 refer to the following kinds of segments: 


Directive Description of Segment 
CODE The segment containing all the code for the 
| module. 
DATA Initialized data. 
DATA? Uninitialized data. Microsoft compilers store 


uninitialized data separately because it can be 
more efficiently stored than initialized data. 


FARDATA and Data placed here will not be combined with 
FARDATA? the corresponding segments in other modules. 


The segment of data placed here can always 
be determined, however, with the assembler 
SEG operator. 


CONST Constant data. Microsoft compilers use this 


segment for such items as string and floating- 
point constants. 


STACK Stack. Normally, this segment is declared in 


the main module for you and should not be 
redeclared. 


The following steps describe how to use Table 6.1 to create directives: 


1. 


Determine what memory model you are using. Then refer to Table 
6.1 to look up the segment name, align type, combine type, and 
class for your code and data segments. Use all of these attributes 
when you define a segment. For example, the code segment for 
small model is declared as follows: 


_LEXT SEGMENT WORD PUBLIC 'CODE' 


The name _TEXT and all the attributes are taken from Table 6.1. 
If the combine type is private, simply do not use any combine type. 


If you have segments in DGROUP, put them into D@ROUP 
with the GROUP directive, as in: 


GROUP DGROUP _DATA _BSS 


Use ASSUME and ENDS as you would normally. Upon entry, DS 
and SS will both point to D@ROUP; therefore, a small-model 
procedure that makes use of D@ROUP should include the follow- 
ing ASSUME directive: 


ASSUME CS: TEXT, DS:DGROUP, SS:DGROUP 


A large-model procedure will assume a different code segment, and 
may assume a far data segment for ES. 
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The following example shows the C-assembly program from Section 6.3, 
without the simplified segment directives from Version 5.0 of the Microsoft 


Macro Assembler: 


_TEXT SEGMENT WORD PUBLIC 'CODE'‘ 


ASSUME cs:_TEXT 
PUBLIC _Power2 
_Power2 PROC 


push bp 
mov bp, sp 
mov ax, [bpt4] 
mov cx, [bpt6] 
shl ax,cl 
pop bp 
ret 

_PowerZ2 ENDP 

_TEXT ENDS 
END 
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Entry sequence - save BP 
Set stack frame 


Load Argl into AX 

Load Arg2 into CX 

AX = AX * (2 to power of CX) 
Leave return value in AX 


Exit sequence - restore BP 
Return 
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Passing by Reference or Value 


Chapter 2 introduced the general concepts of passing by reference and 
passing by value. Chapter 2 also listed the default method used by each 
language. For example, BASIC passes by reference, and Pascal passes by 
value. 


This chapter describes features in each language that override the default. 
For example, using the BYVAL keyword in a DECLARE statement will 
cause BASIC to pass a given parameter by value rather than by reference. 


This chapter is divided into four sections, each of which summarizes 
parameter-passing methods in a particular language, discussing how to 
pass arguments by value, by near reference, and by far reference. To write 
a successful mixed-language interface, you must consider how each param- 
eter is passed by the calling routine and how each is received by the called 
routine. 


7.1 BASIC Arguments 


The default for BASIC is to pass all arguments by near reference. 


~ Note 


Every BASIC subprogram or function always receives parameters by 
near reference. The rest of this section describes how BASIC passes 
parameters only. 


@ Passing BASIC Arguments by Value 

An argument is passed by value when the called routine is first declared 
with a DECLARE statement, and the BYVAL keyword is applied to the 
argument. The use of CALLS overrides this default and passes by far 
reference instead, as mentioned below. 


m= Passing BASIC Arguments by Near Reference 


The BASIC default is to pass by near reference. Use of SEG, BYVAL, or 
CALLS changes this default. 
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m™ Passing BASIC Arguments by Far Reference 
BASIC will pass each argument in a call by far reference when CALLS is 
used to invoke a routine. Using SEG to modify a parameter in a preceding 


DECLARE statement will also cause BASIC to pass that parameter by 
far reference. 


m= Examples 


DECLARE SUB Test (BYVAL a%, b%, SEG c%) 


CALL Test (x%, y%, z%) 

The example above passes the first argument ( a%) by value, the second 
argument ( b%) by near reference, and the third argument { c%) by far 
reference. 


CALLS Test2(x%, y%, z%) 


The example above passes each argument by far reference. 


7.2 C Arguments 


The default for C is to pass all arrays by reference (near or far, depending 
on the memory model) and all other data types by value. C uses far data 
pointers for compact, large, and huge model, and near data pointers for 
small and medium model. 


m Passing C Arguments by Value 


The C default is to pass all nonarrays (which includes all data types other 
than those explicitly declared as arrays) by value. 


Arrays can be passed by value by being declared as the only member of a 
structure. The following example passes all 100 bytes of x directly to the 
function test (). 


struct x_struct {int x[100]} xs; 


test (xs); 
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The function test, in turn, receives the array by declaring a parameter of 
type x_struct. A C routine would interpret this data object as a struc- 
ture, so that structure syntax would be used to manipulate an array ele- 
ment, as in the following example: 


test (x_arrs) 
struct x_struct xX_arrs: 


x_arrs.x[O] = 1; /* set first element to i +/ 


Routines written in other languages, however, would not require structure 
or record syntax. FORTRAN, for example, would access the first element 
simply as X (1). 


m Passing C Arguments by Reference (Near or Far) 
In C, passing a pointer to an object is equivalent to passing the object 


itself by reference. After control is passed to the called function, each 
reference to the parameter itself is prefixed by *. 


Note 


To pass a pointer to a object, prefix the parameter in the call state- 
ment with &. To receive a pointer to an object, prefix the parameter’s 
declaration with *. In the latter case, this may mean adding a second 
* to a parameter which already has a *. For example, to receive a 
pointer by value, declare it as 

int *ptr;: 

but to receive the same pointer by reference, declare it as 


int keptr? 


The default for arrays is to pass by reference. 


m Effect of Memory Models on Size of Reference 
Near reference is the default for passing pointers in small and medium 


model C. Far reference is the default in the compact, large, and huge 
models. 
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Near pointers can be specified with the near keyword, which overrides the 
default pointer size. However, if you are going to override the default 
pointer size of a parameter, then you must explicitly declare the parameter 
type in function declarations as well as function definitions. 


Far pointers can be specified with the far keyword, which overrides the 
default pointer size. 


7.3 FORTRAN Arguments 


The FORTRAN default is to pass and receive all arguments by reference. 
The size of the address passed depends on the memory model. 


= Passing FORTRAN Arguments by Value 


A parameter is passed by value when declared with the VALUE attribute. 
This declaration can occur either in a FORTRAN INTERFACE state- 
ment (which determines how to pass a parameter) or in a function or sub- 
routine declaration (which determines how to receive a parameter). 


A function or subroutine declared with the PASCAL or C attribute will 
pass by value all parameters declared in its parameter list (except for 
parameters declared with the REFERENCE attribute). This change in 
default passing method applies to function and subroutine definitions, as 
well as to an INTERFACE statement. 


w Passing FORTRAN Arguments by Reference (Near or Far) 
Passing by reference is the default for FORTRAN. However, if either the 
C or PASCAL attribute is applied to a function or subroutine declara- 
tion, then you need to apply the REFERENCE attribute to any parame- 
ter of the routine that you want passed by reference. 


m@ Use of Memory Models and FORTRAN Reference Parameters 


Near reference is the default for medium-model FORTRAN programs; far 
reference is the default for large-model and huge-model programs. 
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Note 
Versions of FORTRAN prior to 4.0 always compile in large memory 
model. 


You can apply the NEAR attribute to reference parameters in order to 
specify near reference. You can apply the FAR attribute to, reference 
parameters in order to specify far reference. These keywords enable you to 
override the default. They have no effect when they specify the same 
method as the default. 


You may need to apply more than one attribute to a given parameter. In 
that case, enclose both attributes in brackets, separated by a comma: 


REAL*4 X [NEAR, REFERENCE] 


7.4 Pascal Arguments 
The Pascal default is to pass all arguments by value. 


@ Passing Pascal Arguments by Near Reference 


Parameters are passed by near reference when declared as VAR or 


CONST. 
Parameters are also passed by near reference when the ADR of a variable, 
or a pointer to a variable, is passed by value. In other words, the address 


of the variable is first determined. Then, this address is passed by value. 
(This is essentially the same method employed in C.) 


@ Passing Pascal Arguments by Far Reference 


Parameters are passed by far reference when declared as VARS or 
CONSTS. 


Parameters are also passed by far reference when the ADRS of a variable 
is passed by value. 
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Numerical, Logical, and String Data 


This chapter considers the details of passing and receiving kinds of data. 
Discussion focuses on the differences in string format and on the methods 
of passing strings between each combination of languages. 


8.1 Integer and Real Numbers 


Integers and reals are usually the simplest kinds of data to pass between 
languages. However, the type of numerical data is named differently in 
each language; furthermore, not all data types are available in every 
language, and another type may have to be substituted in some cases. 


Table 8.1 shows equivalent data types in each language. 


Warning 


As noted in Table 8.1, C sometimes performs automatic data conver- 
sions which the other languages do not perform. You can prevent C 
from performing such conversions by declaring a variable as the only 
member of a structure and then passing this structure. For example, 
you can pass a variable x of type float, by first declaring the structure: 


struct { 
float x? 
} x_struct; 


If you pass a variable of type char or float by value and do not take 
this precaution, then the C conversion may cause the program to fail. 


8.2 FORTRAN COMPLEX Types 


The FORTRAN types COMPLEX8 and COMPLEX*16 are not 
directly implemented in any other language. However, you can write struc- 
tures in ©, records in Pascal, and user-defined types in BASIC that are 
precisely equivalent. 


The type COMPLE X8 has two fields: the first is a four-byte floating- 
point number that contains the real component, and the second is a four- 
byte floating point number that contains the imaginary component. 
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Table 8.1 
Equivalent Numeric Data Types 
BASIC C FORTRAN Pascal 
t% short INTEGER«2 INTEGER2 
INTEGER int INTEGER 
(default) 
unsigned short” ge WORD 
unsigned 
w&, long INTEGER*#4 INTEGER4 
LONG INTEGER 
(default) 


unsigned long” 


af float’ REAL#4 REAL4 
x REAL REAL 
(default) (default) 
SINGLE 
at double REAL#8 REAL8 
DOUBLE DOUBLE 7 
| 3 PRECISION 
unsigned char! CHARACTER+#13 
BOOLEAN 


* Not available in BASIC, FORTRAN, or Pascal. A signed integer may be 
substituted, but take care not to exceed range. 


TC automatically converts float to double in assignment or when passed by value. 


f : eucp ees) converts char and unsigned char to int in assignment or when passed 
y value. 


8 The FORTRAN type CHARACTER*1 is not the same as LOGICAL. The data type 
LOGICAL is covered in Section 8.3. 
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The type COMPLEX*«16 is similar to COMPLEX#8, with the only 
difference being that each field contains an eight-byte floating-point 
number. 


The type COMPLEX is equivalent to the type COMPLEX#8. 


Float real component 
HUBS Suu Ria hie 


sha or 


Figure 8.1 FORTRAN COMPLEX Data Format 


8.3 FORTRAN LOGICAL Type 


The FORTRAN LOGICAL type is not equivalent to either the Pascal 
BOOLEAN or C char type. Instead, a FORTRAN LOGICAL «2 is 
stored as a one-byte indicator value (l=true, O=false) followed by an 
unused byte. A FORTRAN LOGICAL«4 is stored as a one-byte indicator 
value followed by three unused bytes. The type LOGICAL is equivalent 
to LOGICAL#4, unless 8STORAGE:2 is in effect. 


To pass or receive a FORTRAN LOGICAL type, declare a C structure, 
Pascal record, or BASIC user-defined type, with the appropriate fields. 


8.4 Strings 


Strings are stored in a variety of formats. Therefore, some transformation 
is frequently required to pass strings between languages. 


This section presents the string format(s) used in each language, and then 
describes methods for passing strings within specific combinations of 
languages. 


8.4.1 String Formats 


The following section describes how a string is stored by each language, as 
well as how a string is passed as an argument. 
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= BASIC String Format 
Strings are stored in BASIC as four-byte string descriptors: 


Figure 8.2 BASIC String Descriptor Format 


The first field of the string descriptor contains a two-byte integer indicat- 
ing the length of the actual string text. The second field contains the 
address of this text. This address is an offset into the default data area 
and is assigned by BASIC’s string-space management routines. These 
management routines need to be available to reassign this address when- 
ever the length of the string changes, yet these management routines are 
only available to BASIC. Therefore, other languages should not alter the 
length of a BASIC string. 


m C String Format 

C stores strings as simple arrays of bytes and uses a null character (numer- 
ical 0, ASCII NUL) as delimiter. For example, consider the string declared 
as follows: 


char str[] = "String of text" 


The string is stored in 15 bytes of memory as: 


Figure 8.3 C String Format 
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Since str is an array like any other, it is passed by reference, just as 
other C arrays are. To pass by value, declare the array as a member of a 
structure. (See Section 7.2, “C Arguments,” for more information.) 

B FORTRAN String Format 

FORTRAN stores strings as a series of bytes at a fixed location in mem- 
ory. There is no delimiter at the end of the string as in C. Consider the 
string declared as follows: 


STR = ‘String of text' 


The string is stored in 14 bytes of memory as: 


tr fifefof fol fr 


Figure 8.4 FORTRAN String Format 


Strings are passed by reference, just as other FORTRAN data are. Al- 
though Version 4.0 of the FORTRAN Optimizing Compiler has a method 
for passing length, the variable length FORTRAN strings cannot be used 
in a mixed-language interface because other languages cannot access the 
temporary variable that FORTRAN uses to communicate string length. 


Pascal String Format 


Pascal has two types of strings, each of which uses a different format: a 
fixed-length type STRING and the variable-length type LSTRING. 


The format used for STRING is identical to the FORTRAN string for- 
mat, described above. 


The format of an LSTRING stores the length in the first byte. For exam- 
ple, consider an LSTRING declared as: 


VAR STR:LSTRING (14) ; 
STR := ‘String of text' 
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The string is stored in 15 bytes of memory. The first byte indicates the 
length of the string text. The remaining bytes contain the string text | 
itself: 


Figure 8.5 Pascal String Format 


8.4.2 Passing BASIC Strings 


When a BASIC string (such as A$) appears in an argument list, BASIC 
passes a string descriptor rather than the string data itself. The BASIC 
string descriptor is not compatible with the string formats of the other 


languages. 


Warning 


When you pass a string from BASIC to another language, the called 
routine should under no circumstances alter the length of the string. 
Other languages lack BASIC’s string-space management routines. 
Therefore, altering the length of a BASIC string is lable to corrupt 
parts of the BASIC string space. Changes that do not affect length, 
however, are relatively safe. 


The routine that receives the string must not call any BASIC routine. 
If it does, BASIO’s string-space management routines may change the 
location of the string data without warning. 


However, the SADD and LEN functions extract parts of the string 
descriptor. SADD extracts the address of the actual string data, and 
LEN extracts the length. The results of these functions can then be 
passed to other languages. 


BASIC should pass the result of the SADD function by value. Bear in 
mind that the string’s address, not the string itself, will be passed by 
value. This amounts to passing the string itself by reference. The BASIC 
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module passes the string address, and the other module receives the string 
address. The address returned by SADD is declared as type integer, but 1s 
actually equivalent to a C near pointer or Pascal ADR variable. 


Pass LEN (A$) as you would normally pass a two-byte integer. 


“# Passing BASIC Strings to C 


Before attempting to pass a BASIC string to C, you may want to first 
append a null byte on the end, with an instruction such as: 


As = A$ + CHRS (0) 


The string now conforms to the C string format. Note that when used in a 
BASIC string expression the + indicates concatenation, or joining, of two 
strings. 


There are two methods for passing a string from BASIC to C. The first 
method 1s to pass the string address and string length as separate argu- 
ments, using the SADD and LEN functions. If you are linking to a C 
library routine, this is the only workable method. 


DECLARE SUB Test CDECL(BYVAL S%, BYVAL N%) 
CALL Test (SADD (A$), LEN (A$)) 


void Test(s, n) 
char near *s; 
int n; 


{ 


In the example above, SADD (A$) returns the near address of the string 
data. This address must be passed by value, since it is equivalent to a 
pointer (even though treated by BASIC as an integer). Passing by refer- 
ence would attempt to pass the address of the address, rather than the 
address itself. 


C must receive a near pointer since only the near (offset) address is being 
passed by BASIC. Near pointers are the default pointer size in medium- 
model C. 


The second method is to pass the string descriptor itself, with a call state- 
ment such as: 


CALL Test2 (A$) 
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In this case, the C function must declare a structure for the parameter, 
which has the appropriate fields (length and address) for a BASIC string 
descriptor. The C function should then expect to receive a pointer to a 
structure of this type. 


@ Passing BASIC Strings to FORTRAN 


FORTRAN variable-length strings (available in Version 4.0) cannot be 
used in a mixed-language interface. 


Use the SADD function to pass the address of a BASIC string. The FOR- 
TRAN routine should declare a character variable of the same length 
(which is fixed). 


DECLARE SUB Test (BYVAL 5%) 
As="abcd" 
CALL (SADD (A8) ) 


FORTRAN SOURCE 


1M» 


SUBROUTINE TEST (STRINGA) 
CHARACTER*s4 STRINGA [NEAR] 


In the example above, SADD (A$) should be passed by value, since it is 
actually an address and not an integer. (Passing a string by reference is 
equivalent to passing the string address by sal as that CHARAC- 
TER«4 STRINGA [NEAR] declares a fixed-length parameter received by 
near reference. 


FORTRAN must receive by near reference. The NEAR attribute makes 
this adjustment, since the FORTRAN default is to receive by far reference. 


& Passing BASIC Strings to Pascal 


The same technique used to pass a string to FORTRAN can be used to 
pass a string to Pascal. However, the Pascal routine should declare the 
string as a VAR parameter, in order to receive the string by near refer- 
ence. The Pascal code must declare the fixed-length type string (4) ina 
separate statement, then use the declared type in a procedure declara- 
tion. 
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DECLARE SUB Test (BYVAL 5%) 
AsS="abcd" 
CALL Test (SADD (A$) ) 


type stype4=string (4); 
procedure Test (VAR StringA:stype4) ; 


8.4.3 Passing C Strings 

When a C string appears in an argument list, C passes the address of the 
string. (A C string is just an array and so is passed by reference.) C can 
easily pass data to a fixed-length FORTRAN or Pascal string, or to BASIC 
in the form of a string descriptor. 

# Passing C Strings to BASIC 

_ To pass a C string to BASIC, first allocate a string in C. Then create a 


structure identical to a BASIC string descriptor. Pass this structure by 
near reference, as in the example below: 


char cstr[] = "ABC"; 


struct { 
char ssd_addr:; 
int sd_len: 

} str_des; 


str_des.sd_addr = cstr; 
str_des.sd_len = strlen(cstr); 
bsub (&str_des) ; 


Make sure that the string originates in C, not in BASIC. Otherwise, 
BASIC may attempt to move the string around in memory. 


m@ Passing C Strings to FORTRAN and Pascal 


To pass strings to FORTRAN and Pascal, it is only necessary to make 
sure that the called routine receives the string by reference and allocates 
sufficient space. FORTRAN and Pascal should expect to receive fixed- 
length strings; to declare a fixed-length string parameter in Pascal you 
must first declare a type, as shown below. 
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m Example 


/* C code - calls Pascal and FORTRAN */ 
/* large memory model assumed +/- 


char a[]="abcd"; 


Testl1 (a); /* call to FORTRAN +«/ 
Test2 (a); /* call to Pascal +#/ 


{* Pascal x*} 

module Ptest1; 

type stype4 : string(4); 

procedure Testl(vars StringA : stype4) 


FORTRAN 


aa 


SUBROUTINE TEST2 (A) 
CHARACTER*4 A 


However, © cannot pass variable-length strings to FORTRAN; the FOR- 
TRAN string data are not placed on the stack, but require special low- 
level variables found only ina FORTRAN program. | 


8.4.4 Passing FORTRAN Strings 
Variable-length FORTRAN strings of type CHARACTER+(x) (available 


in Versions 4.0 and later) cannot be effectively passed to other languages. 
However, fixed-length strings can be passed without much difficulty; the 
principal limitation is that the FORTRAN INTERFACE must declare _ 
the length of the string in advance. 


By default, FORTRAN passes strings by reference. However, if you apply 
the C or PASCAL attribute to a routine, then the default changes to 
passing by value. The actual string data do not include a delimiter, unless 
you use the C-string feature described below. 


= Passing FORTRAN Strings to BASIC 


FORTRAN cannot directly pass strings to BASIC because BASIC expects 
to receive a string descriptor when passed a string. Yet there is an indirect 
method for passing FORTRAN strings to BASIC. First, allocate a fixed- 
length string in FORTRAN, declare an array of two-byte integers, and 
treat the array as a string descriptor. Next, assign the address of the 
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string to the first element (using the LOC function), and assign the length 
of the string to the second element. Finally, pass the integer array itself by 
reference. BASIC can receive and process this array just as it would a 
string descriptor. 


# Passing FORTRAN Strings to C 


The C-string feature overrides the normal FORTRAN format and pro- 
duces strings that can be effectively manipulated by C. When the C-string 
feature is used, a null byte is appended to the end of the string, and 
backslashes that appear in a literal-string text are treated as escapes. 


You convert FORTRAN strings to C strings by simply typing C immedi- 
ately after a string constant. Do not insert commas or any other interven- 
ing punctuation, only spaces. Note that the length of the string is in- 
creased by one because of the null byte that is appended. You need to 
allow for this when you declare string variables. 


The following example passes the address of a string to C. The string is in 
the C format. 


m Example 


INTERFACE TO SUBROUTINE CONV [C] (S81) 
CHARACTER*5 S1 [REFERENCE] 
END 


CHARACTER+5 S1 
Sl = 'abcd' C 
CALL CONV (S1) 


In the example above, note that an additional byte is allocated for S1, in 
consideration of the null byte added by the C-string conversion (done on 
the line above the call). Also note that the REFERENCE keyword was 
necessary because the C attribute in the first line changes the parameter- 
passing default to calling by value. 


= Passing FORTRAN Strings to Pascal 


The FORTRAN and Pascal fixed-length string types are equivalent and 
therefore can be easily passed between FORTRAN and Pascal. 


FORTRAN modules should only pass fixed-length strings to Pascal. The 
Pascal routines, in turn, should expect to receive fixed-length strings. To ° 
specify a fixed-length string parameter in Pascal, you first need to declare 
a type, as in the example below. 
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m Example 


C FORTRAN SOURCE CODE 


INTERFACE TO SUBROUTINE PS (S1) 
CHARACTER+4 S1 
END 


Sl = ‘wxyz' 
CALL PS (S81) 
END 


{ Pascal module} 


module Psmod; 
type stype4 = string(4); 
procedure ps (vars strl : stype4); 


8.4.5 Passing Pascal Strings 


The Pascal data type LSTRING is not compatible with the formats used 
by the other languages. You can pass an LSTRING indirectly, however, 
by first assigning it to a STRING variable. Pascal supports such assign- 
ments by performing a conversion of the data. 


Important 


Pascal passes an additional, two-byte parameter that indicates string 
length whenever you pass a parameter of type STRING or of type 
LSTRING. To suppress the passing of this additional parameter, you 
first declare a fixed-length type, as shown in the example in the sec- 
tion, “Passing Pascal Strings to C,” below. 


m Passing Pascal Strings to BASIC 


To pass a Pascal string to BASIC, first allocate a string in Pascal. Next, 
create a record identical to a BASIC string descriptor. Initialize this record 
with the string address and length, and then pass the record by near refer- 
ence. Make sure that the string originates in Pascal, not in BASIC; other- 
wise, BASIC may attempt to move the string data around in memory. 


m Passing Pascal Strings to C 


To pass a string to C, first append a null character (numerical 0, ASCII 
NUL) to the end of the string by using the concatenation operator (*). 
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Then pass the string to C by reference (by declaring the string argument 
as CONST, CONSTS, VAR, or VARS). Remember to first declare the 
fixed-length string type. 


m Example 


program Passtr (input, output); 
type 
stype6 = string(6); 
var 
str : stype6; 
procedure Passtoc (var sl : stype6) [C]: extern; 
begin 
str := ‘abcde’ *« chr (0); 
Passtoc (str); 


You can achieve more flexibility in passing Pascal strings by declaring a 
value parameter of type ADRMEM or ADSMEM and then passing the 
address of the argument. For instance, the example above could be imple- 
mented by first declaring the parameter with the statement, 


procedure Passtoc (sladr : ADRMEM) [C]; extern; 
Then you could make the call with 
Passtoc (ADR str); 


With this method, you can pass strings of different lengths to the pro- 
cedure Passtoc. 


m Passing Pascal Strings to FORTRAN 


The Pascal STRING and the FORTRAN CHARACTER <n types are 
equivalent. Therefore Pascal fixed-length string variables can be freely 
passed to FORTRAN. Usually, you will find it most efficient to pass 
strings by reference (by declaring the string argument as WAR or VARS). 
Remember to first declare the fixed-length type before using it. 


program Passtr (input, output) 
type 
stype6 = string(6); 
var 
str : stype6; 
procedure PasstoF (var sl : stype6); extern: 
begin 
PasstoF (str); 


As explained previously, you can use ADRMEM and ADSMEM to 


achieve more flexibility in passing strings from Pascal. 


121 


9.6 


; Passing Arrays from BASIC. .......cccscsesecesceee 
9.1.2 Array Declaration and Indexing 


Structures, Records, and 
User-defined Types ........ccccccssssssccssessssccesensssseccees 


EXEC TIIAL DAWA wuecoiwceridecaeoesecoisdveseaiacabivwostdeniaeesese: 


Pointers and Address Variables ............ccsccescescess 


COmmOn DIOCKS wsca,secesscessasnsatsspacteesasaiecwens ee 
9.5.1 Passing the Address 
of the Commion: BIOCK sisisscsaevaiaivescseceaacvicee 


Special Data Types 


This chapter considers special types of data that are either structured (i.e., 
contain more than one field) or are accessed externally. 


9.1 Arrays 


When you program in only one language, arrays do not present special 
problems; the language is consistent in its handling of arrays. When you 
program with more than one language, however, you need to be aware of 
two special problems that may arise with arrays: 


1. Arrays are implemented differently in BASIC, so that you must 
take special precautions when you pass an array from BASIC to 
another language (including assembly). 


2. Arrays are declared and indexed differently in each language. 


This section considers each of these problems in turn. 


Note 


As explained in Chapter 7, arrays cannot be passed by value in C, un- 
less declared within a structure. However, it is usually most efficient to 
pass arrays by reference. 


9.1.1 Passing Arrays from BASIC 


Most Microsoft languages permit you to reference arrays directly. In C, for 
example, an address name is equivalent to the address of the first element. 
FORTRAN and Pascal are similar. This simple implementation is possible 
because the location of data for an array never changes. 


BASIC uses an array descriptor, however, which is similar in some respects 
to a BASIC string descriptor. The array descriptor is necessary because 
BASIC may shift the location of array data in memory; BASIC handles 
memory allocation for arrays dynamically. 


C, FORTRAN, and Pascal do not have any equivalent of the BASIC array 
descriptor. More importantly, they lack access to BASIC’s space manage- 
ment routines for arrays. Therefore, you may safely pass arrays from 
BASIC only if you follow three rules: 


1. Pass the array’s address by applying the VARPTR function to 


the first element of the array and passing the result by value. To 
pass the far address of the array, apply both the VARPTR and 
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VARSEG functions and pass each result by value. The receiving 
language gets the address of the first element and considers it to be 
the address of the entire array. It can then access the array with its 
normal array-indexing syntax. The example below illustrates how 
this works. 


2. The routine that receives the array must not, under any circum- 
stances, make a call back to BASIC. If it does, then the location of 
the array data may change, and the address that was passed to the 
routine will become meaningless. 


3. BASIC may pass any member of an array by value. With this 
method, the above precautions do not apply. 


The following example demonstrates how a BASIC array can be passed to 
FORTRAN. 


mw Example 


REM BASIC SOURCE FILE 
OPTION BASE 1 

DEFINT A-Z 

DIM A(20) 

DECLARE SUB ArrFix (BYVAL Addr AS INTEGER) 


CALL ArrFix (VARPTR(A(1))) 
PRINT A(1) 
END 


C FORTRAN SOURCE FILE 

C 
SUBROUTINE ARRFIX (ARR) 
INTEGER*2 ARR [NEAR] (20) 
ARR(1) = 
END 


In the example above, BASIC considers that the argument passed is the 
near address of an array element. FORTRAN considers it to be the near 
address of the array itself. Both languages are correct. You can use essen- 
tially the same method for passing BASIC arrays to Pascal or C. 


The parameter was declared BYVAL Addr AS INTEGER because a near 
(two-byte) address needed to be passed. If you wanted to pass a far (four- 
byte) address, then the proper code would be: 


DECLARE SUB ArrFix (BYVAL SegAddr AS INTEGER, BYVAL Addr AS INTEGER) 
CALL ArrFix (VARSEG(A(0)), VARPTR(A(O))) 


The first field is the segment returned by VARSEG. If you use CDECL 
then be sure to pass the offset address before the segment address, because 
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CDECL causes parameters to be passed in reverse order: 


DECLARE SUB ArrFix CDECL (BYVAL Addr AS INTEGER, BYVAL SegAddr AS INTEGER) 


CALL ArrFix (VARPTR (A((O)). VARSEG (A (0) )) 


Note 


You can apply LBOUND and UBOUND to a BASIC array, to deter- 
mine lower and upper bounds, and then pass the results to another 
routine. This way, the size of the array does not need to be determined 
in advance. See the Microsoft BASIC Language Reference for more in- 
formation on LBOUND and UBOUND. 


9.1.2 Array Declaration and Indexing 


Each language varies somewhat in the way that arrays are declared and 
indexed. Array indexing is purely a source-level consideration and involves 
no transformation of data. There are two differences in the way that ele- 
ments are indexed by each language: 


1. 


Lower bounds. 


By default, FORTRAN indexes the first element of an array as 1. 
BASIC and C index it as 0. Pascal lets the programmer begin 
indexing at any integer value. Recent versions of BASIC and FOR- 
TRAN also give the user the option of specifying lower bounds at 
any integer values. 


Row-mayjor order vs. column-major order. 


This issue only affects arrays with more than one dimension. With 
row-major order (used by C and Pascal) the leftmost dimension 
changes the fastest. With column-major order need by FOR- 
TRAN, and BASIC by default), the rightmost dimension changes 
the fastest. Thus, in Pascal the first four elements of array X (3, 3) 
are: 


Misty -xXto) “xis, 6 re 
In FORTRAN, the four elements are: 
X(1,1) X(2,1) X(3,1)  X(1,2) 


The example above assumes that both the Pascal and FORTRAN arrays 
use lower bounds of 1. Table 9.1 shows equivalences for array declarations 
in each language. In this table, ris the number of elements of the row 
dimension (which changes most slowly), and c is the number of elements of 
the column dimension (which changes most quickly). 
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Table 9.1 
Equivalent Array Declarations 
Language Array Declaration Notes 
BASIC DIM 2z(¢-1,r-1) with default lower 
bounds of 0 
e type a{r|{c] when passed by 
reference 
struct { when passed by 
type a[r|[c]3} 2 value 
FORTRAN type 2(¢,r) with default lower 
bounds of 1 
Pascal grarray|a..a+r—1,b..b+c-1] 
of type 


The declarations above extend to any number of dimensions that you may 
use. For example, the C declaration 


int arri [2] [10] [15] [20] 
is equivalent to the FORTRAN declaration 


INTEGER*2 ARR1(20, 15, 10, 2) 


# Example 


The following references all refer to the same place in memory for an 
array: 


arr1[2] [8] (in C) 

Arri [3,9] (in Pascal, assuming lower bounds of 1) 
ARR1 (9, 3) (in FORTRAN, assuming lower bounds of 1) 
ARR1 (8, 2) (in BASIC, assuming lower bounds of 0) 


When you use BASIC with the BC command line, you can select the /R 
compile option, which specifies that row-major order is to be used, rather 
column-major order. 
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Note 


The constants used in a C array declaration represent dimensions, not 
upper bounds as they do in other languages. Therefore, the last ele- 
ment in the C array declared as int arr [5] [5] is not arr [5] [5], 
but arr [4] [4]. 


9.2 Structures, Records, and 
User-defined Types 


The C struct type, the BASIC user-defined type, and the Pascal record 
type are equivalent. Therefore, these data types can be passed between C, 


Pascal, and BASIC. 


However, these types may be affected by the storage method. By default, C 
and Pascal use word alignment (unpacked storage) for all data except 
byte-sized objects and arrays of byte-sized objects. This storage method 
specifies that occasional bytes may be added as padding, so that word and 
double-word objects start on an even boundary. (In addition, all nested 
structures and records start on a word boundary.) The following illustra- 
tion shows the the contrast between packed and unpacked storage: 


Figure 9.1 Structure and Record Storage 
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If a structure or record is being passed between them, it Is important that 
a calling routine and the called routine agree on storage method. Other- 
wise, data will not be properly received. The simplest method for ensuring 
compatibility between all three languages is simply to turn on packing for 
C and Pascal modules. The packed storage method may sacrifice some 
speed, but it has the advantage of creating smaller executable files. 


9.3 External Data 


You can always share data between two languages by passing parameters. 
In the case of local variables and all BASIC variables, passing parameters 
is the only convenient way to share data. 


However, C, FORTRAN, and Pascal routines can access data directly that 
are external. The term “external” refers to data that are both static and 
public; in other words, the data are stored in a set place in memory (static, 
unlike dynamic or local data, which are allocated on the stack), and the 
data have been made publicly available to other modules. Compilers make 
a data object (variable, structure or array) available by placing its name, 
along with size and type information, into the object file. 


External data (data that can be directly accessed by any other module 
can be defined in a C, FORTRAN, Pascal, or assembly module. Note that 
a data definition is distinct from an external declaration. A definition 
causes a compiler to create a data object; an external declaration informs 
a compiler that the object is to be found in another module. 


There are three requirements for programs that share external data be- 
tween languages: 


1. One of the modules must define the static data. 


You can define a static data object in a C or FORTRAN module by 
defining a data object outside all functions and subroutines. (Do 
not Ne the static keyword in C with a data object you wish to be 
public. 


2. The other modules that will access the data must declare the data 
as external. 


In C, you can declare data as external by using an extern declara- 
tion, similar to the extern declaration for functions. In FORTRAN 
and Pascal, you can declare data as external by adding the 
EXTERN attribute to the data declaration. 


3. Resolve naming-convention differences. 
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In C, you can adopt the BASIC/FORTRAN/Pascal naming con- 
vention by applying fortran or pascal to the data declaration. In 
FORTRAN and Pascal, you can adopt the C naming convention by 
applying the C attribute to the data declaration. 


The examples below help illustrate the general language features of exter- 
nal data just described. 


” Examples 


/* C source code +*/ 


int thingl1; /* Thingl is public and static +«/ 

extern int thing2; /* Thing2Z is defined in another module +*/ 
static int thing3; /* Thing3 is static, but not public +/ 
ctest () 

4 


C FORTRAN SOURCE CODE 


EG 
INTEGER*2 THING1 [C, EXTERN] 
INTEGER*2 THING2 [C] 
C 
C  THING1 DEFINED IN ANOTHER MODULE, USING C CONVENTION (_thing1) 
C  THING2 DEFINED HERE, USING C CONVENTION (_thing2) 


{ Pascal source code } 


module Ptest; 
procedure Test; 
var 
thingl [C, EXTERN] : integer; { Both vars defined elsewhere } 
thing2 [C, EXTERN] : integer; { and use C naming convention } 


In the examples above, the variables thingl and thing2 are defined and 
declared with the C naming convention so that they will be placed into 
each object file as __thingl and _thing2. However, you can Just as easily 
specify the BASIC/FORTRAN/Pascal naming convention, by using the 
following C statements: 


int fortran thingl; 
extern int fortran thing2; 


The C attribute can then be dropped from the FORTRAN and Pascal 
source code. Each object file will contain the names THING1 and THING2. 
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9.4 Pointers and Address Variables 


Rather than passing data directly, you may want to pass the address of a 
piece of data. Passing the address amounts to passing the data itself by 
reference. In some cases, such as BASIC arrays (see Section 9.1.1), passing 
an address is the only way to share particular kinds of data between two 
languages. 


The Pascal ADR and ADS types are equivalent to near and far pointers, 
respectively, in C. You can pass ADR and ADS variables as ADRMEM 
or ADSMEM. BASIC and FORTRAN do not have formal address types. 
However, they do provide ways for storing and passing addresses. 


BASIC programs can access a variable’s segment address with VARSEG 
and its offset address with VARPTR. The values returned by these 
intrinsic functions should then be passed or stored as ordinary integer 
variables. If you pass them to another language, pass by value. Otherwise 
you will be attempting to pass the address of the address, rather than the 
address itself. 


To pass a near address, pass only the offset; if you need to pass a far ad- 
dress, you may need to pass the segment and offset separately. Pass the 
segment address first, unless CDECL is in effect. 


FORTRAN programs can determine near and far addresses with the LOC 
and LOCFAR functions. Store the result as INTEGER«2 (with the 
LOC function) or as INTEGER «4 (with the LOCFAR function). 


As with BASIC, if you pass the result of LOC or LOCFAR to another 
language, be sure to pass by value. 


9.5 Common Blocks 


You can pass individual members of a FORTRAN or BASIC common 
block in an argument list, Just as you can with any data. However, you can 
also give a different language module access to the entire common block 

at once. 


Pascal and C modules can reference the items of a common block by first 
declaring a structure or record, with fields that correspond to the common 
block variables. (For an example, see the next section.) BASIC modules 
can also employ a user-defined type to access the fields of a FORTRAN 
common block. 
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Having defined a structure, record, or user-defined type with the appropri- 
ate fields, the Pascal or C module must then connect with the common 
block itself. The next two sections each present a method for gaining 
access to common blocks. 


9.5.1 Passing the Address 
of the Common Block 


To pass the address of a common block, simply pass the address of the 
first variable in the block. (In other words, pass the first variable by refer- 
ence.) The receiving C or Pascal module should expect to receive a struc- 
ture (or record) by reference. 


@ Example 


In the example below, the C function initcb receives the address of the 
variable N, which 1t considers to be a pointer to a structure with three 


fields: 


C FORTRAN SOURCE CODE 
c 
COMMON /CBLOCK/N,X,Y 
INTEGER+2 N 
REAL#8 X,Y 


CALL INITCB(N) 


/* C source code «/ 


struct block_type { 


int n: 
double x: 
double y: 


}3 


initcb (block_hed) 
struct block_type *block_hed:; 


block _ hed->n = 1: 
block hed->x = 10.0: 
block_hed->y = 20.0; 
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9.5.2 Accessing Common Blocks Directly 
You can access FORTRAN common blocks directly by defining a structure 


(or record in Pascal) with the appropriate fields and then using the meth- 
ods described in Section 9.3, “External Data.” 


m” =Example 
In the example below, cblock is declared as an external structure. You 


can reference the individual fields of cblock which will correspond to 
those of the common block CBLOCK in the FORTRAN source file. 


struct block_type { 


int n: 
double x: 
double y;>? 


}: 


extern struct block_type fortran cbhlock; 


9.6 Using a Varying Number of Parameters 


Some C functions, most notably printf, can be called with a different 
number of arguments each time. To call such a function from another lan- 
guage, you need to suppress the type-checking that normally forces a call 
to be made with a fixed number of parameters. In BASIC, you can remove 
this type checking by omitting from the DECLARE statement a param- 
eter list, as explained in Section 2.2, “Alternative BASIC Interfaces.” In 
FORTRAN or Pascal, you can call routines with a variable number of 
parameters by including the VARYING attribute in your interface to 
the routine, along with the C attribute. You must use the C attribute 
because a variable number of parameters is only feasible with the C calling 
convention. 


The VARYING attribute prevents FORTRAN or Pascal from enforcing a 
matching number of parameters. Each time you call the routine, you will 
be able to pass more or fewer parameters than are declared in the interface 
to the routine. However, each actual parameter that you pass will be 
type-checked against whatever formal parameters you may have declared 
in the interface. FORTRAN or Pascal will compare the type of the first 
actual parameter to the first formal parameter (if any), the second actual 
parameter to the second formal parameter, and so on. 
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Because the number of parameters is not fixed, the routine you call should 
have some mechanism for determining how many parameters to expect. 
Often this information is indicated by the first parameter. For example, 
the C function printf scans the format string passed as the first parame- 
ter. The number of fields in the format string determines how many addi- 
tional parameters the function should expect. 


The example below demonstrates the use of the VARYING attribute to 
call printf directly from Pascal (the program needs to be compiled and 
linked to the C large memory model so that printf is linked in). 


” Example 


program Test (input, output); 
type 
stype30 : string(30); 
var 
strl : string(30); 
str2 : string(10); 
n : integer; 
procedure printf (vars sl : stype30) [C, VARYING]; extern: 
begin 


strl = 'This is %s string, number %d.' * chr (0); 
str2 = 'formatted' * chr(Q); 
n= 1; 


printf(strl, str2, n); 
end. 


In Pascal, you can write the interface to printf so that the format string 


can be of varying lengths, by using the ADRMEM feature. See Section 
8.4.5, “Passing Pascal Strings,” for more information. 
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Chapter 1 


Introduction 


Welcome to the Microsoft® Editor. The Microsoft Editor is a powerful software 
development tool that runs in OS/2 systems and in DOS 2.1 and above. It lets you 
create source files, customize editing functions, and invoke compilers (or other utilities 
such as assemblers). The pages that follow use the term “OS/2” to refer to both the 
Microsoft Operating System/2 (MS@ OS/2) and IBMe OS/2. Similarly, the term 

“DOS” is used to refer to both MS-DOS@ and PC-DOS where appropriate. 


You can use the Microsoft Editor as a simple text editor, but it is particularly useful for 
writing programs. The following list describes some of the flexible ways you can use 
the editor: 


Compile and Link Programs from within the Editor 


The Microsoft Editor 1s more than a text editor; it1s a development environ- 
ment. Develop programs more quickly by compiling from within the editor. If 
the compile fails, then view the errors, rewrite the program, and recompile—all 
without leaving the editor. 


Customize the Editor 


The Microsoft Editor lets you reassign editing functions to different keys. You 
can specify function assignments in the initialization file; the editor automati- 
cally recognizes these assignments each time you run it. You can change these 
function assignments at any time during an editing session. 


Write New Editing Functions in C 


If you use Microsoft C, then you can write new editing functions for the Micro- 
soft Editor. Write a C-language module using the standard C data and control- 
flow structures, and call the editor’s low-level editing functions to read and 
write to a file. The editor loads the module into memory and calls it on 
command. 


Save Typing Effort with Macros 
A macro is a command which performs a series of predefined actions; for ex- 


ample, a macro can insert a given phrase or word or perform an entire series of 
editing commands. Define a macro, then invoke it with one keystroke. 
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Edit Complex Files with Windows 


When you edit a large file, you may want to view different parts of the file 
simultaneously. With the Microsoft Editor, you can split up your screen into as 
many as eight windows, each displaying a different part of the file. 


Handle Multiple Source Files 


With a simple command, you can transfer back and forth between the different 
files that you are working on—there is no need to leave the editor and then start 
it up again. Furthermore, as the editor moves between files, it saves cursor posi- 
tion and other relevant information. You can view portions of different files 
simultaneously by using windows. 


1.1 System Requirements 


To use the Microsoft Editor, you need to have MS OS/2 running in protected mode, or 
DOS 2.1 or above with at least 128 kilobytes (K) of available memory. A minimum of 
150K of available memory is required to use the C extensions described in Chapter 8. 


1.2 Using This Manual 


Different parts of the manual address different learning needs, as explained below: 


If you have not used the Microsoft Editor before, you should read Chapter 2, 
“Edit Now,” and Chapter 3, “Command Syntax,” before proceeding. 


To start using the Microsoft Editor right away, read Chapter 2, “Edit Now.” This 
chapter uses a specific example to describe the basic editing functions. 


To get a more general understanding of the many editing functions, read Chapter 
3, “Command Syntax.” This chapter explains how you can specify different 
kinds of arguments for editing functions. Then read Chapter 4, “A Survey of the 
Microsoft Editor’s Commands,” which explores major topics such as searching 
and replacing text, compiling, and creating windows. 


For definitions of terms and concepts, turn to the glossary at the back of the 
manual, Although all terms are defined in the text, you may find it helpful to 
refer to the glossary as you learn about the editor. 
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¢ After you have used the editor to perform simple editing tasks, and understand 
how to enter arguments, you may want to refer directly to Appendix A, “Refer- 
ence Tables.” These tables provide complete descriptions of all functions and 
commands. 


® To use the utility programs (CALLTREE, EXP, MEGREP, RM, and 
UNDEL) that come with the editor, see Appendix B, “Support Programs for 
the Microsoft Editor.” 


The Microsoft Editor comes with a setup program (MESETUP.EXE) that configures 
the editor so that it uses keystroke assignments similar to Microsoft Quick languages 
and WordStare, the BRIEF@ editor, or the Epsilonm editor. It is recommended that you 
work through Chapter 2, “Edit Now,” with the standard defaults for keystrokes, before 
you run the setup program. See the README.DOC file for information on how to use 
the setup program. 


1.3 Typographic Conventions 


The following typographic conventions are used throughout this manual and apply in 
particular to syntax displays for commands and switches: 


Example of 
Convention , Description 


KEY TERMS Bold letters indicate a specific term or punctua- 
tion mark that you must type in as shown. The 
use of uppercase or lowercase letters is not sig- 
nificant. For example, in a function assignment, 
the word Unassigned must be typed in as 
shown, but the first letter need not be capitalized. 


Example: input The typeface shown in the left column is used in 
examples to simulate the appearance of informa- 
tion printed on your screen. The bold version of 
this typeface indicates input entered in response 
to a prompt. 


placeholders Words in italics indicate a field or a general kind 
of information; you must supply the particular 
value. For example, numarg represents a numeri- 
cal argument that you type in from the keyboard. 
You could type in a number, such as 15, but you 
would not type in the word “numarg” itself. 
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[loptional items]} 


{choicel | choice2} 


Repeating elements... 


Program 


Fragment 


KEY NAMES 


“Defined term” 


Items inside double square brackets are optional. 


Braces and a vertical bar indicate a choice 
among two or more items, You must choose one 
of the items unless all of the items are also en- 
closed in double square brackets. 


Three dots following an item indicate that more 
items having the same form may appear. 


Acolumn of three dots tells you that part of a 
program has been intentionally omitted. 


Small capital letters are used for the names of 
keys and key sequences, such as ENTER and 
CTRL+R. Notice that a plus (+) indicates a combi- 
nation of keys. For example, CTRL+E tells you to 


hold down the CTRL key while pressing the E key. 


The names of the keys referred to in this manual 
correspond to the names printed on the IBM Per- 
sonal Computer key tops. If you are using a 
different machine, these keys may have slightly 
different names. 


The cursor movement keys (sometimes called 
“arrow” Keys) that are located on the numeric 
keypad to the right of the main keypad are called 
the DIRECTION keys. Individual DIRECTION keys 
are referred to either by the direction of the 
arrow on the key top (LEFT, RIGHT, UP, DOWN) or 
the name on the key top (PGUP, PGDN). 


Some of the Microsoft Editor’s functions use the 
+, —, or number keys on the numeric keypad, 
rather than the ones on the top row of the main 
keyboard. At each instance, the text notes the 
use of keys from the numeric keypad. 


The carriage-return Key is referred to as ENTER. 


Quotation marks usually indicate a term defined 
in the text. 


Chapter 2 
Edit Now 


This chapter helps you use the Microsoft Editor right away by focusing on the func- 
tions you need to create a simple text file. Functions are built-in capabilities that you 
invoke to give directions to the editor. Most of the chapter consists of a tutorial that 
uses a specific example and features the following functions: 


Function 


Cursor movement 
Insertmode 

Sdelete (stream delete) 
Ldelete (line delete) 

Arg (introduce argument) 
Cancel 

Undo 

Paste 

Psearch (forward search) 
Exit 

Help 


Setfile (move to previous file) 


Default Keystroke 


DIRECTION keys, HOME 
INS 

DEL 
CTRL+Y 
ALT+A 
ESC 
ALT+BKSP 
SHIFT+INS 
F3 

F8 

Fl 


F2 


You can use this tutorial either by starting the editor and typing in each command as 
shown, or you can simply read along. Because the results are explained at each stage, 
you can get a good understanding of the editor just by reading. 


The chapter ends by presenting the complete command line for the editor, with all the 


possible options you may use. 
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2.1 Starting the Editor 


Copy the file M.EXE into your current directory or a directory listed in the PATH en- 
vironment variable. To run the editor in protected mode, copy the file MEP.EXE. (You 
may want to rename the file as M.EXE.) Then start the editor with this command: 


M NEW.TXT 


The Microsoft Editor responds by asking if you want to create a new file by this name. 
Press Y to indicate yes. The editor creates the file, and you are ready to enter text. 


2.2 The Microsofte Editor’s Screen 


When you start the editor with a new file, you see a screen that is mostly blank (see 
Figure 2.1): 


Cursor 


Copyright (C) Microsoft Corp 1987. All rights reserved 


ane (text) Length=8 Windouw=(1,1) 


Dialog line Status line 


Figure 2.1 Microsoft Editor’s Screen 


Edit Now 


The cursor first appears at the upper-left corner of the screen. Even though the file is 
empty, you can use the DIRECTION keys—denoted as UP, DOWN, LEFT, and RIGHT—to 
move the cursor anywhere on the screen. (The DIRECTION keys are the arrow keys on 
the numeric keypad.) Try experimenting with cursor movement. 


The next-to-bottom line is called the “dialog line,” which is reserved for displaying 
messages from the editor and letting you enter text arguments. The bottom line is 
called the “status line,” and it always displays the following fields: 


Field Description 

c:new.txt File name, with complete path 

(text) Type of file 

Length=1 Length of file, in number of lines (minimum 
value is 1) 

Window= (1,1) Window or cursor position 


The field Window= (1,1) indicates that the upper-left corner of the screen corre- 
sponds to the first row and column of the file. As you scroll through files that are 
larger then one screen, the numbers in this field change. See Section 7.4.2, “Boolean 
Switches,” to learn how to alter this field so that it displays cursor position instead of 
window position. 


2.3 Sample Session 


Once the Microsoft Editor is started, you can enter text immediately. Simply start typ- 
ing, and press ENTER when you want to begin a new line. By default, the editor starts 
in “overtype” mode, which means that anything you type replaces the text at the cursor 
position. 


To begin, type in the following text. There are some deliberately planted errors that 
you'll correct in a few moments. 


It’s mind over matter. 
What is mind? 

No mat matter. 

Wh is matter? 

Mever mind._ 


The third, fourth, and fifth lines have errors near the beginning of each line. To get to 
the beginning of the fifth line, you could press the LEFT key until you got to the begin- 
ning of the line. However, you can get there faster by pressing the HOME key. This key 
moves the cursor to the first nonblank character in the line. 
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Now move the cursor to the beginning of the fifth line and correct the error by typing 
the letter N: 


Never mind, 


2.3.1 Inserting Text with the Insertmode Function 


To insert text in this example, move the cursor to the third position in the fourth line: 
Wh_is matter? 


The letters at need to be inserted at the end of the first word. Press the INS Key to in- 
voke the Insertmode function, which toggles between overtype and insert mode. You'll 
see the word insert appear at the end of the status line. Type the letters at to pro- 
duce the following line: 


What_is matter? 


2.3.2 Removing a Word with the Delete Function 


So far, you’ve used editing functions to replace old text and insert new text. The third 
line requires text deletion, so move the cursor to the beginning of the second word in 
the third line: 


No mat matter. 


One of the text-deletion functions is Sdelete, which stands for “stream delete.” Invoke 
the Sdelete function by pressing the DEL key. You can use the Sdelete function in differ- 
ent ways. For example, you can delete the character at the current cursor position by 
just pressing the DEL key. You can also delete a group of characters with the following 
sequence: 


ALT+A move-cursor DEL 


Section 2.3.3, “Introducing the Arg Function,” examines this command sequence in 
detail. 


2.3.3 Introducing the Arg Function 


To invoke the Arg function, press ALT+A by holding down the ALT key and then 
pressing A. 


The Arg function does nothing by itself; you use it to introduce an argument to another 
function. (An arguments 1s information, such as text or highlighted characters, that the 
function works with.) In this case you’ll use the Arg function to highlight the group of 


Edit Now 


characters you wish to delete. After pressing ALT+A, move the cursor to the beginning 
of the third word. Your screen should appear as follows: 


Never mind. 


Copyright (C) Microsoft Corp 1987. All rights reserved 


e:\z\neu. txt Ctext) Length=S Window=(1,1) 


Now press DEL, and the highlighted characters are removed. 


2.3.4 Canceling and Undoing Commands 


If you pressed ALT+A at the wrong time but did not complete the command you were 
typing, you can cancel the argument by pressing the ESC key. This keystroke invokes 
the Cancel function. The Cancel function lets you start a command sequence over 
again. 


If you complete a command that was incorrect, reverse the command by pressing 
ALT+BKSP (hold down the ALT key and then press the backspace key). This keystroke 
invokes the Undo function. If you invoke Undo again, it reverses the next-to-last 
editing command. Invoke Undo a third time, and it reverses the second-to-last editing 
command, and so on. The number of commands that the editor remembers is control- 
led by the undocount switch, discussed in Chapter 7, “Using the TOOLS.INI File.” 
The default number of commands remembered is 10. 
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2.3.5 Using Ldelete to Move Text 


As is the case with other editors, delete functions in the Microsoft Editor serve a dual 

purpose: deleting text and moving text. The last text deleted is placed into the “Clip- 

board.” (The Clipboard is a special section of memory that holds text placed there by coe 
the Copy, Ldelete, or Sdelete functions.) When you press SHIFT+INS, which invokes the | 
Paste function, the contents of the Clipboard are inserted into the file. 


The stream-delete function (Sdelete, presented above) is useful for deleting a series of 
characters on the same line, The line-delete function, Ldelete, provides the most effi- 
cient way of deleting entire lines. In this section, Ldelete will be used to move two 
complete lines of text. Consider the current text: 


It’s mind over matter. 
What is mind? 

No Matter. 

What is matter? 

Never mind. 


Move the cursor to any place in the fourth line. Then select the bottom two lines by 
pressing ALT+A and then pressing the DOWN key once. You should see the bottom two 
lines highlighted, as follows: 


What is matter? 
Never mind. 


Copyright (C) Microsoft Corp 1987. All rights reserved 
G:\osZ\zdos\neu.txt Ctext modified) Length=S Window=(1,1) 


Now invoke the Ldelete function by pressing CTRL+Y. The two lines disappear. In 
general, the Ldelete function deletes whatever characters you highlight. 
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Having deleted a block of characters, you are now ready to use the Paste function 
(SHIFT+INS) to put the deleted text into a new location in your document. Move the cur- 
sor to the beginning of the top line and press SHIFT+INS. You should now see the fol- 
lowing text: 


What is matter? 

Never mind. 

It’s mind over matter. 
What is mind? 

No matter. 


You can also invoke Paste with an argument. Try this sequence of keystrokes: 
1. Press ALT+A. 


2. Type the following text: 
The Philosopher said, 


3. Press SHIFT+INS. 


The result is that the words The Philosopher said, are inserted at the current 
cursor position. The Philosopher said, is an example of a “text argument.” 
Text arguments automatically appear on the dialog line, so you can see what you’re 
typing. Use DEL to correct errors as you’re typing a text argument. 


2.3.6 Searching with Psearch 


The Psearch function takes different kinds of arguments and applies them in a con- 
sistent way. The term Psearch stands for “‘plus search,” and means the same thing as 
“forward search.” This function, which is assigned to the F3 key, takes both text argu- 
ments and cursor-movement arguments. You can ask the editor to locate the next occur- 
rence of the word mind by typing the word in as a text argument. Move the cursor to 
the beginning of the file, then try the following sequence of keystrokes: 


1. Press ALT+A. 


2. Type the following text: 


mind 
3. Press F3. 


You can achieve the same result by moving the cursor to the beginning of the word | 
mind on the screen, then highlighting the word with the following sequence of 
keystrokes: 


ALT+A RIGHT RIGHT RIGHT RIGHT F3 


11 


Microsoft Editor User’s Guide 


An even easier way of selecting the word is to give the keystroke sequence ALT+A F3, 
which selects the word at the current cursor location. This word (all characters up to 
the first blank or new-line character) becomes the search string. 


Often when you use the Psearch function, you want to look repeatedly for some text 
string. To search for a text string previously specified, press F3 by itself. 


2.3.7 Exiting the Editor 


Press F8 to leave the editor. The F8 key sequence invokes the Exit function, which auto- 
matically saves any changes you have made to the file and exits. 


2.4 Getting Help 


As you work with the Microsoft Editor, you may occasionally forget which function 
is assigned to which key. Press Fi to get a complete list of all key assignments. You 
examine this list the way you edit a file; use the DIRECTION keys, PGUP, and PGDN 

to navigate through the list. You may see that some functions are unassigned. In later 
chapters, you’ ll learn how to assign these functions to keystrokes. 


Press F2 to get back to your file. The F2 key invokes the Setfile function, which always 
takes you back to the file you were editing. 


2.5 The Microsoft Editor’s Command Line 


Use the following command line to start up the editor: 
M{[/D] [/e commana] [[/t] [files] 


If you are using the protected-mode version, then the name of the editor’s executable 
file is MEP.EXE. You can rename this file to M.EXE. 


The /D option prevents the editor from examining TOOLS.INI for initialization set- 
tings (see Chapter 7, “Using the TOOLS.INI File,” for more information). 


The /e option enables you to specify a command upon startup. The command argument 
is a String that follows the same syntax rules as those given for macros in Chapter 6, 
“Function Assignments and Macros.” If command contains a space, then the entire 
string should be enclosed by double quotes. | 


The /t option specifies that any files edited in this session are temporary. The editor 
will not list these files in the information file after this session 1s terminated. 
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If a single file is specified, then the editor attempts to load the file. If the file does 

not yet exist, the editor asks you if you want to create the file. If multiple files are 
specified, the first file 1s loaded; then, when you invoke the Exit function, the editor 
saves the current file and loads the next file in the list. If no files are specified, then the 
editor attempts to load the file you were editing when you last exited the editor. 


Upon startup, the status line displays at least four fields. The status line can display up 
to eight fields, as follows: 


1. Name of the file being edited 

2. Type of file (based on extension) 

3, The word modified if the file has been changed 

4, The letters NL if no carriage returns were found when the file was loaded (that 
is, if the file did not contain carriage returns to denote the end of each line, but 
used only line feeds) 

5. The length of the file, in lines 

6. Cursor position or window position of upper-left corner 


7. The word insert if you are in insert mode 


8. The word meta if you have invoked the Meta function 
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Command Syntax 


If you’ve worked through Chapter 2, “Edit Now,” you already have an understanding 
of the flexibility of commands in the Microsoft Editor. Many of the editing functions 
accept a variety of arguments—text arguments, cursor-movement arguments (which 
you select by highlighting), or no argument at all. In this chapter, youl learn about 
each kind of argument. The chapter also presents the syntax conventions used 
throughout the manual. 


Topics are covered in the following order: 
¢ Commands and functions 
e Entering a command 
e Argument types 
® Text arguments (numarg, markarg, textarg) 


¢ Cursor-movement arguments (streamarg, linearg, boxarg) 


3.1 Commands and Functions 


This manual often refers to “commands” and “functions.” While these two concepts 
are closely related, they are not necessarily the same. 


A command is a complete instruction, providing the editor with all the information that 
it needs to carry out a specific activity. Acommand may consist of a single function, or 
it may consist of several functions and an argument. 


A function is a built-in editing capability. You invoke a function with a specific key- 
stroke. Chapter 6 explains how to assign keys to functions, but most functions have de- 
fault keys already assigned to them. 
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Each command can include at most one argument. An argument can consist of text that 
you type in, or characters on screen that you highlight with cursor movement. The ar- 
gument is passed to the function that follows it. 


Note 


Throughout this manual, function names are given in italics and are capitalized 
(for example: Paste). Argument types are given in italics and are lowercase (for 
example: textarg). Although functions correspond to specific keystrokes, argument 
types are fairly broad categories. For example, textarg corresponds to any line of 
text that you explicitly type as an argument. See Sections 3.3-3.5 for more 
information. 


3.2 Entering a Command 


This section explains how to enter a command, A command can be as simple as a 
single function, or it may be more complex. 


The following three rules describe the general syntax of a command. You do not need 
to memorize these rules; they are provided here for the sake of understanding. 


1. You must use the Arg prefix (press ALT+A) when introducing an argument. 


2. You can use Arg Arg (press ALT+A twice) in place of Arg. Some functions attach 
a special meaning to Arg Arg. 


3. Some functions recognize the Meta (F9) prefix. 


The first rule 1s that you use the Arg function (ALT+A) when you want to introduce an 
argument. The general syntax of a command that uses the Arg function is: 


Arg argument Function 


This syntax applies regardless of the type of argument you enter. As soon as you in- 
voke Arg (by pressing ALT+A), the editor highlights the current cursor position. This 
position stays fixed, even if you enter new text or continue to move the cursor. 
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The following list gives examples of the Arg argument Function syntax: 


Command Default Keystrokes 

Arg textarg Psearch | ALT+A type-characters F3 
Arg linearg Ldelete ALT+A move-cursor CTRL+Y 
Arg streamarg Sdelete ALT+A move-cursor DEL 


You can also use the Arg prefix without specifying an argument, for example, ALT+A 
F3, When you do not explicitly give an argument, the function following Arg assumes 
some argument based on the cursor position. For example, ALT+A F3 takes the word at 
the cursor position as the argument. 


The second rule of syntax is that some functions recognize the prefix Arg Arg (press 
ALT+A twice) as well as the prefix Arg. You use Arg Arg to introduce an argument just 
as you do with Arg; however, the use of Arg Arg modifies the function’s effect in some 
predefined way. For example, consider the following commands: 


Command Default Keystrokes 
Arg textarg Psearch ALT+A type-characters F3 
Arg Arg textarg Psearch ALT+A ALT+A type-characters F3 


The first command searches for an ordinary text string, whereas the second command 
recognizes a special string called a “regular expression.” See Chapter 5 for more infor- 
mation on regular expressions. 


The third rule of syntax is that some functions accept the optional prefix Meta (F9). 
The Meta prefix alters the effect of the function in some predefined way. For example, 
whereas Up moves the cursor up one line, Meta Up (F9 UP) moves the cursor up to the 
top of the screen. 


When you invoke Meta, the phrase (meta) is displayed on the status line. The Meta 
prefix, if used, should occur just before the function that it modifies. Thus the follow- 
ing are examples of valid commands: 


Command Default Keystrokes 

Meta Right F9 RIGHT 

Arg Meta Compile ALT+A F9 F5 

Arg textarg Meta Setfile ALT+A type-characters F9 F2 
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3.3. Argument Types 


The Microsoft Editor provides two basic ways to enter arguments: you can enter text 
directly, as part of the command (text argument), or you can use cursor movement to 
highlight characters on the screen (cursor-movement argument). Each of these two 
methods has several variations, as shown in the following list: 


1. Text argument. After you invoke Arg (ALT+A), continue to type characters. These 
characters appear on the dialog line (the line next to the bottom of the screen). 
You can give three different kinds of text arguments: 


A numarg, which consists of a string of digits. 


b. Amarkarg, which is a string containing the name of a previously defined 
file marker. 


c. A textarg. A text argument not recognized as a numarg or markarg; it is 
considered simply a textarg. 


2. Cursor-movement argument. After you invoke Arg, the current cursor position is 
highlighted. Highlight more characters by moving the cursor to a new position. 
You can give three different kinds of cursor-movement arguments: 


a. A streamarg, in which the old and new cursor positions are in the same line 


b. A linearg, in which the old and new cursor positions are in a different line 
but in the same column 


c. <A boxarg, in which the old and new cursor positions are in a different line 
and column 


Sections 3.3.1 and 3.3.2 give more detailed information on each type of argument, 
along with examples. 


3.3.1 Text Arguments (numarg, markarg, textarg) 


After you invoke Arg (ALT+A), you can enter a text argument by typing any printable 
characters, including blank spaces. As soon as you begin entering text, the dialog line 
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on the screen (next to the bottom line of the screen) shows the word Arg: followed by 
your text. For example, if you press ALT+A and then type the letter T, you see the fol- 
lowing items on the dialog line: 


Arg: T 
When you enter a text argument, you can use the following six editing capabilities: 


1. Erase the character at the current cursor position with the Sdelete function (DEL). 


2. Backspace to the left, while erasing a character, with the Cdelete function 
(CTRL+G). 


3. Move back and forth nondestructively with LEFT and RIGHT. If you use RIGHT to 
move past the end of current input, the editor inserts a character from the 
previous text argument. 


4. Insert a space at the cursor position with the Sinsert function (CTRL+J). 


5. Move to beginning of the text with Begline (HOME) and to the end of the text 
with Endline (END). 


6. Clear characters to the end of the line with the Arg function (ALT+A). 


Sections 3.3.1.1—3.3.1.3 present the possible variations of text arguments. 


3.3.1.1 The numarg Type 


A numarg is string of digits that you enter as a text argument. Each of the three follow- 
ing examples is a numarg: 


3 


del. 
45 


The number must be a valid decimal integer. A numarg is evaluated as a number and 
not as literal text. Typically, it is used to indicate a range of lines starting with the 
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cursor position. For example, the following command sequence deletes 10 lines 
starting with the cursor position: 


1. Invoke Arg (press ALT+A). 
2. Type the following text: 
10 


3. Invoke Ldelete (press CTRL+Y). 


Some functions accept text arguments but do not recognize a numarg. In these cases, a 
numarg is treated as an ordinary textarg (see Section 3.3.1.3). 


3.3.1.2 The markarg Type 


A markarg is a file-marker name that you have previously defined with the Mark func- 
tion (CTRL+M). See Section 4.3, “Using File Markers,” for information about Mark. 


Once defined, you can enter the marker name as a markarg. The name is not treated as 
literal text, but is interpreted as an actual file position. For example, the following com- 
mand sequence copies all text between the cursor position and the file position pre- 
viously marked as P1: 
1. Invoke Arg (press ALT+A). 
2. Enter the following text: 
Pl 


3. Invoke Copy (press the + key on the numeric keypad). 


Many functions accept text arguments but do not recognize a markarg. In these cases, 
the markarg is treated as an ordinary fextarg. 
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3.3.1.3 The textarg Type 


A textarg is similar to a numarg or markarg. The only difference 1s that the textarg has 
no special meaning; it is interpreted by the function as literal text. For example, the fol- 
lowing sequence inserts the string Happy New Year into the file, exactly as typed: 


1. Invoke Arg (press ALT+A). 


2. Type the following: 
Happy New Year 


3. Invoke Paste (press SHIFT+INS). 


3.3.2 Cursor-Movement Arguments (streamarg, linearg, boxarg) 


You enter a cursor-movement argument by invoking Arg (ALT+A) and then moving the 
cursor. When you invoke Arg, the current cursor position is marked with a reverse- 
video highlight. This position is called the “initial cursor position.” You then can move 
the cursor; as you do, characters between the initial cursor position and the new cursor 
position are highlighted, as described in Sections 3.3.2.1—3.3.2.3. 


Each function determines how to interpret a cursor-movement argument. Some func- 
tions work with a “stream of text” between the initial cursor position and the new posi- 
tion. A stream of text consists of a continuous series of characters as they are actually 
stored in the file. With a stream of text, the area highlighted is irrelevant; only the two 
positions matter. 


Other functions work with the area highlighted on the screen. As explained in Sections 
3.3.2.2 and 3.3.2.3, this area may be a rectangular box, or it may consist of complete 
lines. 


Chapter 4, “A Survey of the Microsoft Editor’s Commands,” and Appendix A, “Refer- 
ence Tables,” describe how each function interprets cursor-movement arguments. For 
example, Sdelete always deletes a stream of text, whereas Ldelete deletes the area of 
text that is highlighted. 
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3.3.2.1 The streamarg Type 


A streamarg consists of characters on a single line. The term streamarg refers to the 
fact that characters on a single line are always treated as a stream of text, regardless of 
the function involved. 


After invoking Arg, you can move the cursor left or right. A streamarg consists of 
characters beginning with the leftmost of the two positions (initial cursor position or 
new cursor position), up to but not including the rightmost position, as shown in 
Figure 3.1: 


Initial cursor position New cursor position 


char far *name; 

fFlagType (pascal EXTERNAL *func)(); 
unsigned arg; 

unsigned argType; 


typedef struct cmd D@ss~ Ree 


typedef flagType (pascal EXTERNAL *PIF)Cchar far *); 


Union swiftct C 
fFlagType Cpascal EXTERNAL *pFunc)(char far ™); 
int far x*ival; 


FlagTupe far xfval; 
+ 


struct swibdesc f{ 
char far *nane} 
union suiAct act: 
int tupe:; 

oo 


typedef struct swiDesc far »*PSWI: 
alt+p is not assigned to any @ditor Function 
c:\osZ\zdos\ext.h (CC) Length=248 Window=¢ 24, 


Figure 3.1 Sample streamarg 
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3.3.2.2 The limearg Type 


A linearg is defined when the new cursor position is in the same column but on a 
different line from the initial cursor position. The editor responds by highlighting all 
lines between the two cursor positions, including the lines that the cursor positions are 
on. For example, the display in Figure 3.2 1s produced by invoking Arg and then 
pressing DOWN three times: 


Initial cursor position 


char far name; 

flagType Cpascal EXTERNAL *func)();: 
unsigned arg; 

unsigned argType; 


ct cmdDesc far *PCMD; 


typedef flagType Spesee” EXTERNAL, *PIF) (char far = 5 Ped, 


union swifct ra | ; 
FlagType pascal EXTERNAL “prunes (chan far >); 


flagType ar xfuals 


swiDese ¢{ 
char far *name; 
union swiAct act; 
int type; 
¥; 


typedef struct swiDese far *PSWI; 
Argument cancelled 
c:\osz\zdos\ext.h (C) Length=248 Uindow=(24, 1) 


New cursor position 


Figure 3.2. Sample linearg 
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3.3.2.3 The boxarg Type 


A boxarg consists of a rectangular area on the screen. The two corners of the area are 
determined by the initial and new cursor positions. A boxarg is defined when the two 
positions are in both a different line and a different column from each other. 


After invoking Arg, you can move the cursor left or right. The left edge of the box in- 
cludes the leftmost of the two cursor positions. The right edge of the box includes the 
column just to the left of the rightmost of the two cursor positions. The box includes 
parts of all lines between the two positions. 


For example, the display shown in Figure 3.3 is produced by invoking Arg and then 
moving the cursor 3 lines down and 10 columns over: 


Initial cursor position 


char far name; 

flagType (pascal EXTERNAL *funcd(); 
Unsigned arg; 

unsigned argType; 

+3 


ct cmdDesc far *PCMD; 


typedef flagType CEEES-EWMBDEQIERNAL *PIF)(char far ™*); 


union swiftct ¢ 
flagTupe (pasclMeassl, *pFunc)¢char far *); 
int far ival; 
flagType far =*fva 


Union swiAct act; 
int type; 
+3 
typedef struct swiDesc far *PSUWI;: 
Arg: 
c:\os2\zdos\ext.h (CC) Length=248 Window=( 24,1) 


New cursor position 


Figure 3.3 Sample boxarg 
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A Survey of the 
Microsoft Editor’s Commands 


The Microsoft Editor features all the standard capabilities of a text editor: fast naviga- 
tion through a file, and the ability to move blocks of text, search for strings, and handle 
multiple files. In addition, the Microsoft Editor supports a flexible windowing capabil- 
ity for viewing more than one file or more than one part of the same file. The Micro- 
soft Editor can also invoke compilers and assemblers and let you easily view compile 
errors. 


This chapter presents specific editing topics in more detail than they were covered in 
Chapter 2, “Edit Now.” Topics are presented in this order: 


® Moving through a file 

e Inserting, copying, and deleting text 

© Using file markers 

® Searching and replacing text 

e Compiling 

e Using windows 

® Working with multiple files 
Each section presents the most éemition functions within the given topic and gives ex- 
amples of how the functions can be used. If appropriate, the section ends with a brief 


description of other related functions. See Appendix A, “Reference Tables,” for an ex- 
haustive listing of the command syntax for each function. 


4.1 Moving through a File 


Chapter 2, “Edit Now,” described how to the use DIRECTION keys to move through a 
file one space at a time. The DIRECTION keys correspond to the functions Up, Down, 
Right, and Left, to which you can assign different keys if you wish. Chapter 2 also 
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presented the Begline function (HOME), which moves the cursor to the first printable 
character in the current line. Similar to the Begline function is the Endline function 
(END), which moves the cursor just to the right of the last printable character in the cur- 
rent line. 


Each of the four DIRECTION functions has a variation that uses the Meta function as a 
prefix, as shown in the following list. Each of these functions, when used in a com- 
mand with the Meta prefix, moves the cursor as far as possible within the displayed 
screen (or window) without changing column position or causing the screen to scroll 
in any way. 


Command 

(and Default Keystrokes) Description 

Meta Up (F9 UP) Moves the cursor to the top of the screen 

Meta Down (F9 DOWN) Moves the cursor to the bottom of the screen 

Meta Left (F9 LEFT) Moves the cursor to the leftmost position on the 
current line 

Meta Right (F9 RIGHT) Moves the cursor to the rightmost position on 
the current line 


4.1.1 Scrolling at the Screen’s Edge 


You can use the four DIRECTION functions (Up, Down, Right, Left) to cause scrolling. 
The screen (or current window) can scroll in all four directions. Although the editor 
does not wrap lines that are wider than the screen, you can have lines of text that are 
up to 250 characters wide. Use DIRECTION keys to scroll right and left when your text 
lines are wider than the screen or current window. 


Unlike some editors, the Microsoft Editor does not automatically scroll by only one 
column or one line. Instead, the internal switches hscroll and vscroll control how fast 
the editor scrolls. For example, if vscroll (vertical-scroll switch) is set to 7, then the 
editor advances the screen position seven lines when you attempt to move the cursor 
off the bottom of the screen. See Chapter 7, “Using the TOOLS.INI File,” for more in- 
formation on these switches. 


4.1.2 Scrolling a Page at a Time 
The editor provides the Ppage (PGDN) and Mpage (PGUP) functions to move through a 


file more quickly than you can by using the DIRECTION keys to move one line or one 
column at a time. 
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The term “page” is defined as the amount of text that can be displayed in the current 
window or screen. To advance one page forward through a file, invoke the function 
Ppage (PGDN), which stands for “plus page.” 


The Ppage function can appear in a variety of commands that enable you to move even 
faster than a page at a time: 


Command 

(and Default Keystrokes) Description 

Arg Ppage (ALT+A PGDN) Moves the cursor forward to the end of the file 
Arg numarg Ppage Moves the cursor forward by the number of 
(ALT+A numarg PGDN) pages that you specify (numarg) 

Arg streamarg P page Moves the cursor forward by the number 
(ALT+A streamarg PGDN) of pages that you highlight on the screen 


(streamarg) 
The function Mpage (PGUP), which stands for “minus page,” is the direct inverse 
of Ppage, and it accepts the same syntax. For example, the command Arg Mpage 
(ALT+A PGUP) moves you backward to the beginning of the file. 


4.1.3 Other File-Navigation Functions 


The following functions also are useful for moving through a file: 


Function 

(and Default Keystrokes) Description 

Pword (CTRL+RIGHT) Moves the cursor forward (plus) one word 
Mword (CTRL+LEFT) Moves the cursor backward (minus) one word 
Mark (CTRL+M) Defines or moves to a marker 


With the Mark function, you can define a marker or move to a marker. Markers consti- 
tute a special topic, which is discussed in Section 4.3, “Using File Markers.” 


4.2 Inserting, Copying, and Deleting Text 


Often, you need to move, copy, or delete blocks of text. The Microsoft Editor is partic- 
ularly powerful because it provides a variety of ways to define a block of characters. 
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4.2.3 Other Insert Commands 


The following functions insert specific items at the current cursor position (each func- 
tion is acomplete command). These functions do not have preassigned keys; consult 
Chapter 6, “Function Assignments and Macros,” for information on how to assign keys 
to functions. 


Function Description 

Curdate Inserts current date 

Curday Inserts current day of the week 

Curfile Inserts current file name 

Curfileext Inserts current file extension 

Curfilenam Inserts base name of current file 

Curtime Inserts current time 

Curuser Inserts name specified in USER environment variable 


4.2.4 Reading a File into the Current File 


The Paste function can be used in commands that read a file into the current file, as 
shown below: 


Command 
(and Default Keystrokes) Description 
Arg Arg textarg Paste Reads the contents of the file specified by 


(ALT+A ALT+A fextarg SHIFT+INS) the textarg, and inserts these contents into 
the current file. The insertion occurs at the 
current cursor position. 


Arg Arg !textarg Paste Reads the output of the system-level com- 

(ALT+A ALT+A !fextarg SHIFT+INS) — mand line given as the textarg into the 
current file. This command works similarly 
to the command given above. 
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File markers help you move back and forth through large files. Once you have defined 
a file marker, you can move quickly to the location marked. You can also use a file 
marker as input to certain commands. For example, instead of moving the cursor to a 
marked location, you simply give the name of the marker. 


The Microsoft Editor allows you to create any number of file markers. You identify 
each with a name consisting of alphanumeric characters. 


Use the Mark function (CTRL+M) to create or go to a marker. The command Mark 
(CTRL+M with no argument) takes you back to the beginning of the file, just as Arg 
Mpage does. The command Arg Mark (ALT+A CTRL+M) moves you back to the pre- 
vious cursor position. This last use of Mark is useful for switching back and forth 


quickly between two locations. 


Some of the most powerful uses of the Mark function involve commands with argu- 


ments, as shown below: 


Command 
(and Default Keystrokes) 


Arg numarg Mark 
(ALT+A numarg CTRL+M) 


Arg Arg textarg Mark 
(ALT+A ALT+A textarg CTRL+M) 


Arg textarg Mark 
(ALT+A textarg CTRL+M) 


Description 


Moves the cursor to the line that you specify. 
The Microsoft Editor numbers lines beginning 
with the number 0, so the first line of the file is 
line 0, the second is line 1, and so forth. 


Defines a marker at the current location. This 
command sets a marker which in turn can be 
used as input to other functions. 


Moves the cursor directly to a marker that you 
have already defined as a textarg. 
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4.3.1 Functions That Use Markers 


The following functions also make use of markers by accepting a previously defined 
marker name (a markarg) as an argument: 


Function 

(and Default Keystrokes) Description 

Copy (+) Copies the argument into the Clipboard 
Replace (CTRL+L) Executes search and replace 

Qreplace (CTRL#) Executes search and replace, with query for 


confirmation 
* The + key used is the one on the numeric keypad. 


If you specify a marker that the editor cannot find, the editor automatically checks the 
file listed in the markfile switch. See Chapter 7, “Using the TOOLS.INI File,” for 
more information on the markfile switch. 


4.3.2 Related Functions: Savecur and Restcur 


The Savecur and Restcur functions have a purpose that is similar to Mark. The differ- 
ence is that Savecur and Restcur do not take arguments. Use Savecur to save the 
current cursor position, and Restcur to return to that position later. With these two func- 
tions, you can save only one position at a time. 


No keys are preassigned to Savecur or Restcur. See Chapter 6, “Function Assignments 
and Macros,” for information on how to assign keys. 


4.4 Searching and Replacing 


The Psearch function (F3) directs the editor to conduct a forward search (also called a 
“plus search”) for the next occurrence of the specified string. All searches take place 
from the current cursor position to the end of the file. 
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The most common uses of Psearch consist of the following commands: 


Command 

(and Default Keystrokes) Description 

Arg textarg Psearch Directs the editor to look for the string given as 

(ALT+A textarg F3) textarg. The editor scrolls the screen, if neces- 
sary, and moves the cursor to the next occur- 
rence of textarg in the file. 

Psearch (F3) Directs the editor to look for the previous search 
string. 

Arg Psearch Directs the editor to take the word at the current 

(ALT+A F3) cursor position as the search string. (In other 

swords, the search string consists of all characters 

from the cursor to the first blank or new line.) 

Arg streamarg Psearch Directs the editor to take text highlighted on the 

(ALT+A streamarg F3) screen as the search string. 


You can search backward with Msearch (which stands for “‘minus search”). The 
Msearch function (F4) uses syntax identical to Psearch. Backward searches take place 
from the current cursor position to the beginning of the file. 


4.4.1 Searching for a Pattern of Text 


The commands described above search for an exact match of the string you specify. 
However, sometimes, you may want to search for a set of different strings: for ex- 
ample, any word that begins with “B” and ends with “ing.” 


You can search for a pattern of text by specifying a “regular expression.” A regular ex- 
pression is a string that specifies a pattern of text by using certain special characters. 
Chapter 5 describes the regular-expression character set and syntax in detail, with ex- 
amples of use. 


The command Arg Arg textarg Psearch (ALT+A ALT+A textarg F3) searches forward for 
a string that matches the regular expression specified as the textarg. The command 
Arg Arg textarg Msearch (ALT+A ALT+A textarg F4) searches backward for a string that 
matches the regular expression specified as the textarg. 
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4.4.2 Search-and-Replace Functions 


To replace repeated occurrences of one text string by another, use the search-and- 
replace function Replace (CTRL+L). By default, the replacement happens from the cur- 
sor position to the end of the file. However, as described below, you can restrict the 
range over which the replacement happens. 


No matter what command syntax you use with Replace, the editor reacts by prompting 
you for a search string and a replacement string, and then executing the search and re- 
place. If you have used Replace or Qreplace before, the previous value of the search or 
replace string appears on the message line. To use the string displayed, press ENTER. 
To edit the string or enter a completely new string, use the text-editing commands 
given in Section 3.3.1, “Text Arguments.” Note that the Arg function clears characters 
to the end of the line. 


The commands Replace and Arg Replace are identical to each other, and execute re- 
placement from the current cursor position the end of the file. You can also specify a 
range for the replacement by using one of the following commands: 


Command Default Keystrokes 
Arg linearg Replace ALT+A linearg CTRL+L 
Arg numarg Replace ALT+A numarg CTRL+L 
Arg boxarg Replace ALT+A boxarg CTRL+L 
Arg markarg Replace ALT+A markarg CTRL+L 


If you specify a numarg, the replacement happens over the specified number of lines 
beginning with the current line. The argument boxarg defines a rectangular area within 
which the replacement takes place. And if you specify a markarg, then the replacement 
occurs in the box of text between the cursor position and the marker. 


The Replace function is most efficient when you are sure that you want the replace- 
ment to be executed in every case. If you want to regulate how often the replacement 
occurs, use Qreplace (CTRL+\). This function is identical in every way to Replace and 
takes exactly the same syntax. The only difference is that Qreplace (short for “query 
replace”) prompts you for confirmation before each replacement. Qreplace asks you to 
press Y for yes, N for no, or P, which causes replacement to proceed without 

further confirmation. The Cancel function (ESC) terminates the replacement. 


The Replace and Qreplace functions both take regular expressions as search strings 
when you introduce the argument with Arg Arg instead of Arg. (See Chapter 5 for infor- 
mation on regular expressions.) Otherwise, syntax is identical, and the functions accept 
the same arguments. 
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4.5 Compiling 


One of the strengths of the Microsoft Editor is that you can use it as a development en- 
vironment. You can write a program and compile (or assemble) from within the editor. 
If the compile fails, you can make corrections to the source file at the same time that 
you view the errors and then compile again. 


Ordinarily a compiler reports error output directly to the screen while you are outside 
of any editor. But when you compile from within the Microsoft Editor, it displays your 
errors by moving the cursor to the position where the error was found, and by re- 
porting the corresponding message on the dialog line. This way, you can view the con- 
text of the error more easily and make corrections as soon as you see the errors. 


The Compile function (SHIFT+F3) can be used to view errors as well as to compile. This 
Compile function appears in a variety of different commands, as shown in Sections 
4.5.1-4.5.2. 


4.5.1 Invoking Compilers and Other Utilities 


When you run the editor in OS/2 protected mode, compiles run in the background and 
the editor beeps when the compile is completed. When you run the editor in real mode, 
you have to wait until the compile is completed before you can perform further editing 
commands. 


With the Microsoft Editor’s compile capability, you can invoke any program or utility 
you want, and specify any command-line options you want. To invoke a program 
directly, use one of the following commands: 


Command Default Keystrokes 

Arg Arg textarg Compile ALT+A ALT+A textarg SHIFT+F3 
Arg Arg streamarg Compile ALT+A ALT+A Streamarg SHIFT+F3 
Arg Compile ALT+A SHIFT+F3 


In the commands above, textarg is a system-level command line that you type in, and 
streamarg is a system-level command line that you highlight on the screen. Usually, it 
is most convenient to set your compile command once by setting the extmake switch 
and giving the command Arg Compile each time you want to compile. 


The extmake text switch can be set to invoke a particular command line. A “text 
switch” is an internal string variable that affects the editor’s behavior. See Chapter 7, 
“Using the TOOLS INI File,” for more information on text switches and how to 

set them. 
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Furthermore, the information on extmake in Chapter 7 describes how to make the edi- 
tor sensitive to the file extension of your current file. For example, Arg Compile in- 
vokes one command line if the file has a .C extension, and another if it has an .ASM 
extension. 


4.5.2 Viewing Error Output 


To view error output from within the editor, you must use a compiler or assembler that 
outputs errors in one of the following formats: 


filename row column: message 
filename (row, column): message 
filename (row): message 
filename: row: message 
"filename", row column: message 


The Microsoft Editor, in turn, reads the error output directly, and responds by moving 
the cursor to each location where an error was reported while displaying the message 
on the dialog line. (The method for moving between error locations is described 
below.) The following programs output error messages in a format readable by the 
Microsoft Editor: 


¢ Microsoft C Optimizing Compiler 
® Microsoft Macro Assembler 
® Microsoft Pascal Compiler 4.0 


® Microsoft BASIC Compiler 6.0 


Note 


With the Pascal and BASIC compilers, you must use the /Z command-line option 
with either the PL or BC driver to generate error output that the Microsoft Editor 
can read. (The extmake switch, discussed in Chapter 7, “Using the TOOLS.INI 
File,” uses the /Z option by default.) 


When a compile fails and the compiler reports errors, the editor moves the cursor to 
the first error location reported. To view the next error, give the command Compile 
(SHIFT+F3). You can make any changes needed before advancing to the next error. If 
you are running in protected mode, you can move backward to the previous error by 
giving the command Arg Meta Compile (ALT+A F9 SHIFT+F3). 
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In protected mode, the editor processes all error messages through a pipe. In real 
mode, the editor redirects compile-error output to the file M.MSG. If the errors are not 
in readable format, then you can view errors by loading this file. 


4.6 Using Windows 


A “window” is a division of the screen that functions independently from other por- 
tions of the screen. When you have two or more windows present, each functions as a 
miniature screen; one window can view lines 5—15 while another window views lines 
90-97. You can even use windows to view two or more files simultaneously. The cur- 
sor is never in more than one window. You can scroll each window independently. 


Although windows are tiled, they can view overlapping areas of text. With multiple 
windows onto the same file, any change you make while in one window can affect 
what is displayed in another. Changes are reflected simultaneously in all windows that 
view the same area of altered text. 


You can have up to eight windows on the screen, and you can create either horizontal 
or vertical divisions between windows. You move between windows by giving the 
command Window (Fé with no arguments). To create or merge a window, move the cur- 
sor to the row or column at which you want to create a new division, then give one of 
the following commands: 


Command 

(and Default Keystrokes) Description 

Arg Window Creates a horizontal window (split at the cursor 
(ALT+A F6) column) 

Arg Arg Window Creates a vertical window (split at the cursor 
(ALT+A ALT+A F6) row) 

Meta Window Closes the current window by merging it with an 
(F9 F6) adjacent window 


Each window must have a minimum of 5 lines and 10 columns. If you try to create a 
window of a smaller size, then the command fails. 


37 


Microsoft Editor User’s Guide 


4.7 Working with Multiple Files 


You can load a new file into the current screen or window with the Set¢file function. 
Consider the following commands that use the Setfile function: 


Command 
(and Default Keystrokes) Description 
Arg textarg Setfile Loads the file specified in the textarg. 


(ALT+A textarg F2) 


Setfile (F2) Loads the previous file. You can use Seffile to 
move back and forth between two files. 


An easier way to use to use Seéfile, however, is to follow these steps: 
1, Bring up the information file with the Information function (press SHIFT+F1). 
2. Use the UP and DOWN keys to move to the name of a file. 


3. Select the file that the cursor is on by giving the command Arg Seffile (press 
ALT+A F2), 


The information file contains the names of all files that you have edited before, up to 
the limit specified by the tmpsav switch. (See Chapter 7, “Using the TOOLS. INI 
File,” for more information about switches.) Active files—tfiles that have been edited 
during this session—are listed with their current lengths. 


When an old file is reloaded, the editor remembers cursor and window information 
from the last time you edited the file. The editor stores this information in the file 
M.TMP. 


The Arg textarg Setfile command accepts wild-card characters (? matches any 
character and * matches any string) in the textarg. The command responds by display- 
ing a list of files that match the textarg. You can then select a file by using the steps 
outlined above. For example, the following sequence causes the editor to list all files 
with a .c extension: 


1. Invoke the Arg function (press ALT+A). 


2. Type the following: 


ee @ 


3. Invoke the Se¢file function (press F2). 
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A regular expression is a special kind of string that you can use in a Microsoft Editor 
search command. Instead of matching only one string, a regular expression can match 
a number of different strings. For example, the regular expression a [123] matches 
any of the following strings: 


Regular expressions have their own particular syntax. This chapter explains that syntax 
and gives examples. Topics are covered in this order: 


¢ Regular expressions as simple strings 
® Special characters 

® Matching method 

¢ Tagged expressions 


* Predefined regular expressions 


You can use regular expressions with the MEGREP utility (see Appendix B, “Support 
Programs for the Microsoft Editor,” for more information on this utility). You can also 
use regular expressions with the search functions (Psearch, Msearch, Replace, and 
Qreplace). Each of these functions recognizes a regular expression (rather than an ordi- 
nary text string) when you use Arg Arg to introduce the string. 


5.1 Regular Expressions as Simple Strings 


The power of regular expressions comes from the use of the special characters listed 
below. If you do not use these special characters, then a regular expression works as an 
ordinary text string. 


\EFOL] t+: 27 4$4+* @# 
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For example, the regular expression match me precisely matches only a literal oc- 
currence of itself, because it contains no special characters. 


5.2 Special Characters 


The Microsoft Editor offers a rich set of pattern-matching capabilities. Most of the 
special characters described below have analogues in other editors and utilities that use 
regular expressions. 


The list below describes some of the simpler special characters. The term class has a 
special meaning defined below. All other characters should be interpreted literally. 


Expression Description 


\ Escape. Causes the editor to ignore the special meaning of 
| the next character. For example, the expression \? matches 
? in the text file; the expression \* matches *; and the ex- 
pression \\ matches \. 


4 Wildcard. Matches any single character. For example, the ex- 
pression a?a matches aaa, aBa, and ala, but not aBBBa. 


A Beginning of line. For example, “The matches the word 
The only when it occurs at the beginning of a line. 


$ End of line. For example, end$ matches the word end only 
when it occurs at the end of a line. 


[class] Character class. Matches any one character in the class. Use 
a dash (-) to specify ranges. For example, [a-~zA-Z0-9] 
matches any character or digit, and [abc] matches a, b, or 
oF 


[~class] Noncharacter class. Matches any character not specified in 
the class. 


The rest of the special characters are described in the following list, in which X isa 
placeholder that represents a regular expression that is either a single character or a 
group of characters enclosed in parentheses (()) or braces ({}). The placeholders XJ, 
XZ, and so on, represent any regular expression. 
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Expression 


xX* 


Xx@ 
xX# 


(X11X2!...1Xn) 


~X 


XAn 
{...} 


letter 


Regular Expressions 


Description 


Minimal matching. Matches zero or more occurrences of X, 
For example: the regular expression ba*b matches baaab, 
bab, and bb. 


Minimal matching plus (shorthand for XX*), Matches one or 
more occurrences of X. The regular expression ba+b 
matches baab and bab but not bb. 


Maximal matching. Identical to X*, except for differences in 


- matching method explained in Section 5.3. 


Maximal matching plus. Identical to X+, except for differ- 
ences in matching method explained in Section 5.3. 


Alternation. Matches either X/, X2, and so forth. It tries to 
match them in that order, and switches from Xi to Xi+/ only 
if the rest of the expression fails to match. For example, the 
regular expression (ww! xx!xxyy) zz matches xxzz on 
the second alternative and xxyyzz on the third. 


Not function. Matches nothing, but checks to see if the string 


matches X at this point, and fails if it does. For example, 
“~ (if !while) ?*$ matches all lines that do not begin 
with if or while. 


Power function. Matches exactly 1 copies of X. For example, 
w*4 matches wwww and (a?) *3 matches a#aba5. 


Tagged expression. The exact use of tags is explained in Sec- 
tion 5.4. Characters within braces are treated as a group. 


Predefined string. The list of predefined strings is given in 
Section 5.5. 
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The example below uses some of the special characters presented in this section. To 
find the next occurrence of a number (that is, a string of digits) beginning with a digit 
1 or 2, perform the following sequence of keystrokes: 


1. Invoke Arg twice (press ALT + A twice). 
2. Type the following characters: 
[12][0-9]* 


3. Invoke Psearch (press F3). 


5.3. Matching Method 


The “matching method” you use 1s significant only when you use a search-and-replace 
function. The term matching method refers to the technique used to match repeated ex- 
pressions. For example does a* match as few or as many characters it can? The an- 
swer depends on the matching method. Two matching methods are available: 


Method Description 


Minimal The minimal method matches as few characters as possible 
in order to find a match. For example, a+ matches only the 
first character in aaaaaa. However, ba+b matches the en- 
tire string baaaaaab, as if is necessary to match every oc- 
currence of a in order to match both occurrences of b. 


Maximal The maximal method always matches as many characters as 
it can. For example, a# matches the entire string aaaaaa. 


The significance of these two methods may not be apparent until you use search and 
replace. For example, if a+ (minimal matching plus) is the search string and EE 1s the 
replacement string, then 


addaa 
is replaced with 
EEEEEEREEEE 


because each occurrence of a is immediately replaced by EE. However, if a # (maxi- 
mal matching plus) is the search string, then the same string is replaced with 


BE 


because the entire string aaaaa is matched at once and replaced with EE. 
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5.4 Tagged Expressions 


Like matching method, tagged expressions have no effect except when you use search- 
and-replace functions. Tagged expressions are useful because you may want to manipu- 
late text rather than simply replace it with a fixed string. For example, suppose you 
wanted to find all occurrences of hexdigitsH and replace them with strings of the form 
16#hexdigits. Tagged expressions enable you to do just these kinds of operations. 


The Microsoft Editor first looks for a character string that matches the entire regular 
expression given. Then, each substring of characters that corresponds to an expression 
within braces ({}) 1s tagged. You can tag up to nine such substrings. A tagged expres- 
sion can then be generated in the replacement string by the use of the expression 


$n 


in which n is a digit from 0 to 9. The first tagged expression (going from left to right) 
is referred to as $1, the second as $2, and so forth up to $9. The expression $0 always 
refers to the entire matched string. 


To retum to the original example, you can search for strings of the form hexdigitsH by 
specifying the following regular expression: 


{[0-9a-fA-F]+}H 
and then specifying this replacement string: 
16#$1 


Note that # is not a special character when it appears in the replacement string. The 
result is that the Microsoft Editor searches for any occurrence of one or more hexadeci- 
mal digits (digits 0-9 and the letters a—f) followed by the letter H. The editor then re- 
places each such string by preserving the actual digits, but adding the prefix 16#. For 
example, the string 1a000H 1s replaced with the string 16#1a000. 
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5.5 Predefined Regular Expressions 


The following expressions are defined in Table 5.1 for your convenience. You can use 


them by entering : /etter in a regular expression. 


Table 5.1 

Predefined Expressions 

Letter Meaning 

:a [a~zA-Z0-9} 

tb (IN }#) 

2c [a~zA—Z] 

:d [0-9] 

f ([~'N\<l>+=5,. }#) 

ch ({0-9a-fA-F]#) 

i ([a-zA-Z_$][a-zA-Z0-9_$]@) 
“n ([O-9}#[0-9 j@! [0-9] @.[0-9]#![0-9]#) 
:p ((fa-zZ Ne DANDCECEOW@ 36:2) 
| Ci-"l@"?[~1@’) 

[Ww ([a-zA—Z]#) 

2 ([0-9]#) 
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Description 


Alphanumeric 

White space 
Alphabetic 

Digit 

Portion of a file name 
Hexadecimal number 
C-language identifier 
Number 

Path 

Quoted string 

Word 

Integer 


Chapter 6 
Function Assignments and Macros 


Function assignments and macros give the Microsoft Editor flexibility and power. 
Function assignments allow you to assign any editing function to a new keystroke. The 
new keystroke can be identical to one you have used with other editors, or you can as- 
sign a keystroke that makes sense only to you. 


Using macros saves time by reducing the amount of typing you do. A macro consists of 
a list of arguments and functions; once defined, the entire list of arguments and func- 
tions can be assigned to a single keystroke. The Microsoft Editor’s macros also support 
conditional 2xecution, so that you can use the results of a function (its return value) to 
determine what other functions to invoke. 


This chapter covers the following topics: 
e Using the MESETUP program 
¢ §=6 Assigning functions within the editor 


® Creating macros within the editor 


6.1 Using the MESETUP Program 


The MESETUP program installs the editor files in a directory that you specify and as- 
signs the editing functions to a predefined set of keystrokes. The editor provides con- 
figurations that use keys similarly to the way they are used in several popular editors: 

® Microsoft Quick languages/WordStar 

¢ BRIEF 

® Epsilon 


® Default (which is used if none of the others are selected) 


See the README.DOC file for instructions on using the MESETUP program. 
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6.2 Assigning Functions within the Editor 


Assigning an editing function to a new keystroke from within the editor is easy. And 
once a new assignment has been made, you can use that keystroke to invoke the func- 
tion at any time during the editing session. 


Take into account the following important points when assigning functions to 
keystrokes: | 


Le 


The function assignments you make during the editing session are lost when you 
exit from the editor. See Chapter 7, “Using the TOOLS.INI File,” for 
information on more permanent function assignments. 


Assigning a function to a new keystroke does not change any other keystrokes 
to which the function was previously assigned. See Section 6.2.3 for information 
on removing assignments. 


Only one function may be assigned to.a given keystroke at a me; therefore, you 
are not able to use the keystroke to invoke any function which was previously 
assigned to it. 


6.2.1 Making Function Assignments 


To assign a function to a keystroke, issue the Arg textarg Assign command, where 
textarg uses the following syntax: 


functionname:keystroke 


Here, keystroke may be any of the following: 


1, 
2s 
3. 
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Numeric keys: 0 through 9 
Letter keys: A through Z 


Function keys: F1 through F12 


. Punctuation keys: ‘~,.<>/?;’"({]{}\l-=_+ 


. Named keys: HOME, END, LEFT, RIGHT, UP, DOWN, PGUP, PGDN, INS, DEL, BKSP, 


TAB, ESC 


Function Assignments and Macros 


6. Numeric-keypad keys: +, —, and 0 through 9. To assign a function to the 4 key 
on the numeric keypad, enter the following as the keystroke: 


NUM4 
7. Combinations: 
a. ALT combined with items 1-5 
b. CTRL combined with items 2-6 
c. SHIFT combined with items 3-6 
For example, the function Savecur is assigned to the keystroke CTRL+B in the follow- 
ing way: 
1. Invoke the Arg function (press ALT+A). 


2. Enter the function and keystroke as the textarg by typing the following: 
Savecur:CTRL+B 


3. Invoke the Assign function (press ALT+= by holding down the ALT key and 
pressing the = key). 


From this point on, pressing CTRL+B invokes the Savecur function and saves the cur- 
rent cursor position. 


6.2.2 Viewing Function Assignments 


The Help function shows you what function assignments are in effect at any time 
during the editing session. Invoking the Help function (by pressing F1) causes all of the 
editing functions to be listed in alphabetical order on the screen along with the keys to 
which they are assigned. You can scroll through this information as you would through 
any file. Use the Seéfile function (F2) to return to your original file. 


6.2.3. Removing Function Assignments 

If you choose to remove a function assignment, assign the keystroke to the function 
Unassigned using the Arg textarg Assign command. The argument fextarg uses the fol- 
lowing syntax: 

Unassigned:key 


Here, key is the keystroke you want to remove. 
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For example, to remove the keystroke CTRL+A from any function, perform the follow- 
ing steps: | 


1. Invoke the Arg function (press ALT+A), 


2. Enter the function name as Unassigned and the keystroke by typing the 
following: 


Unassigned: CTRLtA 


3. Invoke the Assign function (press ALT+=). 


After these steps are carried out, pressing CTRL+A does not invoke any functions. 


6.2.4 Making Graphic Assignments “3 


Assigning the Graphic function to a keystroke lets you press the keystroke to insert it 
literally into the file. For example, to insert a form-feed character in the file whenever 
CTRL+L is pressed, follow these steps: 


1. Invoke the Arg function (press ALT+A). 


2. Enter the function Graphic and the keystroke as the textarg by typing the 
following: 


Graphic:CTRL+L 


3. Invoke the Assign function (press ALT+=). 


Like the Graphic function, the Quote function lets you insert a literal character. 
However, the Quote function must be used every time that the keystroke is pressed. 
The Graphic function needs to be assigned only once during an editing session. 


6.3 Creating Macros within the Editor 


A macro is a series of functions and text arguments that you can execute with a simple 
keystroke. The functions may be any valid editor functions. The text arguments may 
serve as input to functions or as text that is to be entered into the file. Macros allow 
you to use the results of a function (its return value) to determine what other functions 
to invoke. 
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Take into account the following important points when creating macros: 


® Macros that you create during the editing session are lost when you exit from 
the editor. See Chapter 7, “Using the TOOLS.INI File,” for information on a 
more permanent way of creating macros. 


¢ The maximum number of macros that may be defined at any one time is 1024. 


6.3.1 Entering a Macro 


Enter a macro by using the Arg textarg Assign command, where textarg uses the syntax 
described below: 


macroname:= {function | " text")... 


Each function must be previously defined and macroname must be a unique name. 
Spaces separate the individual functions and arguments within commands. Double 
quotes surround text arguments. 


For example, the following macro scrolls the window down by 11 lines and places the 
cursor in column 1: 


Halfscreen:=Meta Up Arg "11" Plines Begline 


Since a macro definition must be contained on one line, it may be necessary to break 
up a macro function into several smaller functions as shown in the example below. 
The smaller functions can then be grouped together and given a name and assigned to 
a keystroke. Each of the following lines would be entered one at a time using the 

Arg textarg Assign command. 


Head1l:=Arg wan Linsert WL KKKRKKKEKHEKAKKKHAKKKK KKK EN 

Head2:=Newline "** Routine:" 

Head3:=Newline WAKKKKKKAKKKKKKKKK KAR K KR KK Up Endline Right 
Header:=Headl Head2 Head3 

Macros may contain text only and not use functions at all, as in the following example: 


Proc:="procedure ();" 


When invoked, this macro inserts the text procedure () ; into the file at the current 
cursor position. However, before you can directly invoke the macro, you need to as- 
sign it to a keystroke. 
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6.3.2 Assigning a Macro to a Keystroke 


To invoke a macro, it is necessary to assign it to a keystroke. The procedure is similar 
to that described in Section 6.2.1 for assigning a function to a keystroke, except that 
you enter the name of your macro instead of an editing-function name. For example, 
the following steps assign ALT+H to the macro named Header: 


1. Invoke the Arg function (press ALT+A). 


2. Enter the macro name and keystroke as the textarg by typing the following: 
Header ;ALT+H 


3. Invoke the Assign function (press ALT+=). 


6.3.3 Using Macro Conditionals 


Macro conditionals let you alter the order that functions are invoked within the macro. 
An editing function returns a TRUE value if the function is successful, or a FALSE 
value if it fails. For example, a cursor-movement function fails if the cursor does not 
move or if an invalid argument is used. Table 6.1 provides a complete list of functions 
and return values. 


Table 6.1 

Editor Functions and Return Values 

Function Returns TRUE Returns FALSE 

Arg Always Never 

Argcompile Compile successful Bad argument/compiler not 
found 

Assign Assignment successful Invalid assignment 

Backtab Cursor moved Cursor at left margin 

Begline Cursor moved Cursor not moved 

Cancel Always Never 

Cdelete Cursor moved Cursor not moved 

Compile Compile successful Bad argument/compiler not 
found 

Copy Copy successful Bad argument 

Down Cursor moved | Cursor not moved 
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Function 


Emacscdel 
Emacsnewl 
Endline 
Execute 
Exit 

Help 
Home 
Information 
Initialize 
Insertmode 
Lasttext 
Ldelete 
Left 
Linsert 

- Mark 
Meta 
Mlines 
Mpage 
Mpara 
Msearch 
Mword 
Newline 
Paste 
Phal 
Plines 
Ppage 
Ppara 
Psearch 
Pword 
Qreplace 
Quote 


Returns TRUE 


Cursor moved 

Always 

Cursor moved 

Last command successful 
No return condition 
Always 

Cursor moved 

Always 

Initialization successful 
Insert mode now on 
Function successful 
Line-delete successful 
Cursor moved 


Line insert successful 


Definition/move successful 


Meta now on 
Movement occurred 
Movement occurred 
Movement occurred 
String found 
Cursor moved 
Always 

Always 

Balance successful 
Movement occurred 
Movement occurred 
Movement occurred 
String found 
Cursor moved 

At least one replacement 


Always 


Function Assignments and Macros 


Returns FALSE 


Cursor not moved 


Never 


_ Cursor not moved 


Last command failed 

No return condition 

Never 

Cursor not moved 

Never 

Bad argument 

Insert mode now off 

Bad argument 

Bad argument 

Cursor not moved 

Bad argument 

Bad argument/not found 

Meta now off 

Bad argument 

Bad argument 

Bad argument 

Bad argument/string not found 
Cursor not moved 

Never 

Never 

Bad argument/not balanced 
Bad argument 

Bad argument 

Bad argument 

Bad argument/string not found 
Cursor not moved 

String not found/invalid pattern 


Never 
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Table 6.1 (continued) 


Function 


aig er ne RAE 


Refresh File read in/deleted Canceled, bad argument 

Replace At least one replacement String not found/invalid pattern at 

Resteur Position previously saved with Position not saved with 

Savecur Savecur 

Right Cursor over text of line Cursor beyond end of line 

Savecur Always Never 

Sdelete Delete successful Bad argument 

Setfile File-switch successful Bad argument 

Setwindow Window-change successful Bad argument 

Shell Shell successful Bad argument/program not 
found 

Sinsert Insert successful Bad argument 

Tab Cursor moved Cursor not moved 

Undo Always Never 

Up Cursor moved Cursor not moved 

Window Successful split, join, or move Any error 


The return values listed above can be used with the conditionals shown in Table 6.2 to 
invoke functions conditionally. 


Table 6.2 

Macro Conditionals 

Conditional — Description _ 

:>label Defines a label that can be referenced by any of the other macro 
conditionals. 

=>label Causes a direct transfer to label. If label is omitted, then the current 
macro is exited. 

->label Causes a direct transfer to label if the previous function returned the 
FALSE condition. If label is omitted, then the current macro is 
exited. 

+>label Causes a direct transfer to label if the previous function returned the 


TRUE condition, If label is omitted, then the current macro is exited. 
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For example, the following macro erases all characters from the current line: 
Blankline:=Endline :>back Sdelete Left +>back 
The macro executes the commands in the following order: 

1. Endline causes the cursor to move to the end of the line. 

2. :>back defines a label in the macro command. 

3. Sdelete erases the character under the cursor. 


4. Left moves the cursor one character to the left. If the cursor moves (it is not in 
column 1), then the return condition is true, otherwise it is false. 


5. Ifthe return condition in step 4 is true, +>back transfers control back to the 
command following the label back. 


Steps 3-5 continue until all characters have been deleted and the cursor is in column 1. 
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Chapter 7 
Using the TOOLS.INI File 


You can place statements in the TOOLS.INI file to modify function assignments, set 
switches, and define macros for the Microsoft Editor. Each time the editor is started, it 
loads all of the statements from the appropriate sections of the TOOLS.INI file (un- 
less the /D option is used). This saves you the trouble of entering the same function as- 
signments, switch settings, and macro definitions in every editing session. 


This chapter explains the TOOLS.INI file, as follows: 


¢ Contents of the TOOLS.INI file (comments, function assignments, macros, 
switch settings) 


¢ Location of statements within the TOOLS.INI file (using tags) 


Note 


The editor checks the directories listed in the INIT operating-system environment 
variable for the location of the TOOLS.INI file. For example, if the TOOLS.INI 
file is in the directory C: \ INIT, then place the following statement in your 
AUTOEXEC.BAT file: 


SET INIT=C: \INIT 


7.1 Using Comments 


Comments in the TOOLS.INI file serve the same purpose as comment lines found in 
most program source files; they provide documentation for how and why things are 
done. The Microsoft Editor assumes everything on the line following a semicolon is a 
comment and ignores it. 
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The comment in this example explains the macro’s function and the keystroke assign- 
ment that follows it: 


; Assign Ctrl+S to a macro for saving the current file. 
Save:=Arg Arg Setfile 
Save:Ctr1l+s 


7.2 Assigning Functions to Keystrokes 


Function assignments allow you to assign a function to a particular keystroke, so that 
you can invoke the function by pressing the keystroke. You can change the default set 
of assignments by placing function-assignment statements in the TOOLS.INI file. The 
syntax follows: 


functionname:keystroke 


Here, functionname is the function you want assigned to the keystroke key. Section 
6.2.1, “Making Function Assignments,” lists the keys that you can assign to editing 
functions and macros. 


In the following example, the statement assigns the Window function to the key 
ALT+W: 


Window: Alt+W 


7.3. Defining Macros 


As discussed in Chapter 6, “Function Assignments and Macros,” a macro is made up 
of arguments and predefined functions and can be executed with a single keystroke. To 
enter a macro in the TOOLS.INI file, use the following syntax: 


macroname:= {function |" text"}... 


The argument macroname must be a unique name within each tagged section of the 
TOOLS.INI file. Each function used in the definition must be previously defined. A 
space separates individual functions and arguments in the definition; double quotes sur- 
round the arguments. 
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The example below shows how a multiline macro definition might appear in the 
TOOLS.INI file. 


; This macro indents the first line of each 

; paragraph in the file by five spaces. 

Indent:=Meta Begline Arg Right Right Right Right Right Sinsert 
Inpara:=Mark :>Repeat Indent Ppara Endline Left +>Repeat 
Inpara:Alt+P 


7.4 Setting Switches 


Three types of switches control the action of the Microsoft Editor: numeric switches, 
Boolean switches, and text switches. You can set these switches in one of two ways: 


1. Set them from within the editor using the Arg textarg Assign command, where 
textarg uses the syntax described in the following sections. 


2. Enter them in the TOOLS|INI file, one per line, using the syntax described in 
the following sections. 


7.4.1 Numeric Switches 


Numeric switches allow you to give values to features such as screen colors, tabs, and 
other controls. The syntax for setting a numeric switch is as follows: 


switchname:numericvalue 


In the first example below, the hscroll switch is set to the value of 20, that is, the win- 
dow is shifted left or right by 20 columns when the cursor moves out of the window. 
The second example sets the color of error messages to light yellow text on a black 
background. 


hscroll:20 
errcolor:0E 
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The numeric switches errcolor, fgcolor, hgcolor, infcolor, and stacolor all specify 
colors for various types of text. The first digit of the value specifies the background 
color, while the second digit specifies the text color. Table 7.1 lists the colors and their 
associated hexadecimal values. It should be noted that when specifying the back- 
ground color, the values 8-F specify the same colors as 0-7 respectively, except that 


the text flashes. 


Table 7.1 


Colors and Numeric Values 


Color 


Black 

Blue 

Green 

Cyan 

Red 
Magenta 
Brown 

Light Gray 
Dark Gray 
Light Blue 
Light Green 
Light Cyan 
Light Red 
Light Magenta 
Light Yellow 
White 
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Table 7.2 lists each of the numeric switches, along with its purpose and default value. 


Table 7.2 

Numeric Switches 

Numeric Switch Description (and Default Value) 

entab Controls the degree to which the Microsoft Editor converts multiple 
spaces to tabs when editing a file. A value of 0 means that tabs are 
not used to represent white space, 1 means that all multiple spaces 
outside of quoted strings are converted, 2 means that all multiple 
spaces are converted to tabs. (Default value: 1) 

errcolor | Controls the color used for error messages. The default is red text on 
a black background. (Default value: 04) 

fgcolor Controls the color used for the editing window. The default is light 
gray text on a black background. (Default value: 07) 

height Controls the number of lines that the Microsoft Editor uses in the 
editing window, not including the dialog and status lines. This is 
useful with a nonstandard display device; Enhanced Graphics 
Adapter (EGA) in 43-line mode on the IBM PC uses a value of 41, 
and Video Graphics Array (VGA) in 50-line mode uses a value of 
48. (Default value: 23) 

hgcolor Controls the color for highlighted text. The default is black text on a 
light gray background. (Default value: 70) 

hike Specifies the ending line position of the cursor when the cursor is 
moved directly by editing functions. (Default value: 4) 

hscroll Controls the number of columns shifted left or right when the cursor 
is scrolled out of the editing window. (Default value: 10) 

infcolor Controls the color used for informative text. The default is brown 
text on a black background. (Default value: 06) 

maxmsg Controls the maximum number of messages retained in the Compile 


function’s message buffer. This switch works in OS/2 protected 
mode only. To set this switch, place it in TOOLS.INI in a section 
tagged [M-10.0]. (Default value: 10) 


noise Controls the number of lines counted at a time when searching or 
loading a file. This value is displayed in the lower-right corner of 
the screen and may be turned off by setting noise to 0. (Default 
value: 50) 
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Table 7.2 (continued) 
Numeric Switch 


rmargin 


stacolor 


tabdisp 


tabstops 


tmpsav 


traildisp 


undocount 


vmbuf 


yseroll 


width 


Description (and Default Value) 


Controls the right column margin used in wordwrap mode. Any 
character typed to the right of this margin causes a line break. Word- 
wrap mode is turned on and off with the wordwrap switch. (Default 
value: 72) 


Controls the color used for the status-line information. The default is 
cyan text on a black background. (Default value: 03) 


Specifies the ASCII value of the character used to expand tabs. Nor- 
mally, a space is used, but a graphic character can be used to show 
exactly where tabs are located. (Default value: 32) 


Controls the number of spaces between each logical tab stop for the 
editor. (Default value: 4) 


Controls the maximum number of files about which information is 
kept between editing sessions. These are the most recently edited 
files, and each file will be listed only once. When you exit from the 
editor, the position of the cursor and window are saved, along with 
the layout of multiple windows if any. When you begin editing 

one of these files again, the screen starts up as you left it. (Default 
value: 20) 


Specifies the ASCII value of the character to be displayed as trailing 
spaces. Note that this switch has no effect unless the trailspace 
switch is turned on. (Default value: 0) 


Controls the number of edit functions that you may undo. (Default 
value: 10) 


Controls the number of 2K pages allocated in real memory to buffer 
the virtual-memory file, Mxxx.VM. This switch works in OS/2 pro- 
tected mode only, (Default value: 128) 


Controls the number of lines shifted up or down when the cursor is 
scrolled out of the editing window. The Mlines and Plines functions 
also use this value. (Default value: 7) 


Controls the width of the display mode for displays that are capable 
of showing more than 80 columns. (Default value: 80) 


7.4.2 Boolean Switches 


Boolean switches turn certain editor activities on or off. Turn on a switch by entering 
the switch name followed by a colon; turn it off by typing no followed by the name 
and a colon. The syntax is summarized below: 


[no]]switchname: 
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In the first example below, the case switch is set or turned on, which results in case 
being significant in a search operation. In the second example the askrtn switch is 
reset or turned off, which results in the editor returning from a Shell command without 
prompting you. 


case: 
noaskrtn: 


Table 7.3 provides a complete list of Boolean switches, including the purpose and de- 
fault value for each. 


Table 7.3 

Boolean Switches 

Boolean Switch Description (and Default Value) 

askexit Prompts for confirmation when you exit from the editor. (Default 
value: Off) 

askrin Prompts you to press ENTER when returning from a Shell command. 
(Default value: On) 

autosave Saves the current file whenever you switch away from it. If this 
switch is off, you must specify when you want the file to be saved. 
(Default value: On) 

case Considers case to be significant for search-and-replace operations. 
For example if case is on, the string Procedure is not found as a 
match for the string procedure. (Default value: Off) 

displaycursor Shows a position on the status line in the (row,column) format. 
When off, the position listed is that of the upper-left corner. When 
on, the current cursor position is given. (Default value: Off) 

enterinsmode Starts the editor up in insert mode as opposed to overtype mode. 
(Default value: Off) 

savescreen Saves and restores the DOS screen (for use with the Push and Exit 
functions). (Default value: On) 

shorthames Allows you to specify an alternate file by giving only the base 
name. (Default value: On) 

softer Attempts to indent based upon the format of the surrounding text 
when you invoke the Newline or Emacsnewl functions. (Default 
value: On) 

trailspace Remembers trailing spaces in text. (Default value: Off) 

wordwrap Breaks lines of text when you edit them beyond the margin 


specified by rmargin. (Default value: Off) 
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7.4.3 Text Switches 


Text switches specify a string that modifies the action of the editor in some way. The 


syntax is shown below: 


switchname:textvalue 


In the example below, the backup switch is set so that no backup is performed. 


backup:none 


Table 7.4 lists the text switches, the function of each, and a default value, if any. 


Table 7.4 
Text Switches 


Text Switch 


backup 


extmake 


load 
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Description (and Default Value) 


Determines what happens to the old copy of a file when it is edited. 
A value of none specifies that no backup operation is to be per- 
formed and the old file is overwritten, A value of undel specifies 
that the old file is to be moved so that UNDEL.EXE can retrieve it. 
A value of bak specifies that the file name of the old version of the 
file will be changed to .BAK. (Default value: undel) 


Associates a command line with a particular file extension for use 
by the Compile function. The text after the switch has this form: 


extmake:extension commandline 


Here, extension is the extension of the file to match, and 
commandline is a command line to be executed. If there is a %s in 
the command line, it is replaced with the name of the current file or 
with the textarg in the Arg textarg Compile command. This is the 
only switch that may appear more than once in the TOOLS.INI file; 
there is a separate line for each extension. 


For example, you have the following lines in TOOLS.INT: 


extmake:bc /Z &s 

extmake:for fl /c%&s 

extmake:pas pl /c/hé¢%s 
extmake:asmmasm —Mx $s; 
extmake:ccl/c/Zep /D LINT_ ARGS %s 
extmake:text make %s 


You also have a file named foo. The command Arg foo Compile 
invokes 


make foo 


This in turn invokes a compiler and linker. See the documentation 
for the Microsoft Program Maintenance Utility (MAKE) for more 
information. 

Specifies the name of a C-extension executable file to be loaded. 
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Table 7.4 (continued) 
Text Switch Description (and Default Value) 


markfile Specifies the name of the file the Microsoft Editor searches when 
looking for a marker that is not in the in-memory set. This file can 
be created using the CALLTREE program discussed in Appendix 
B, “Support Programs for the Microsoft Editor,” or by entering lines 
of the following form: 


markername filename line column 


Here, line and column specify the position in the file filename where 
the marker markername appears. 

readonly Specifies the DOS command that is invoked when the Microsoft 
Editor attempts to overwrite a read-only file. The current file name 
is appended to the command, as shown in the following example: 


readonly:attrib-r 


This command removes the read-only attribute from the current file 
so the file can be overwritten. If no command is specified, you are 
prompted to enter a new name under which to save the file. 


7.5 Creating Sections with Tags 


Tags divide the TOOLS.INI file into sections. All statements are associated only with 
the tag that they immediately follow. This allows programs other than the Microsoft 
Editor, MAKE, to use this file for configuration information. It also allows you to load 
only a certain section of statements by using the Arg textarg Initialize command. The 
tag must use the following syntax: 


[M-text] 


The value of text is the textarg that you use to initialize the editor with the statements 
following this tag. A blank line precedes the tag. 


In the example below, there are two tagged sections, one for use with C programs and 
one for Pascal programs. 


[M-—Pascal] 

; Insert a Pascal Header 

Header:=Arg "1" Linsert Newline "{ Pascal Program:" 
Header:Altth 


[M=C 

; Insert a C Header 

Header:=Arg "1" Linsert Newline "/* C Program:” 
Header:Altth 
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With this text in the TOOLS.INI file, you can use ALT+H to insert one of the two head- 
ers into your file, depending on which tag you use to initialize the editor. For example, 
to insert the C header, follow these steps: 


I. 
2. 


4, 


Invoke the Arg function (press ALT+A), 


Enter the name of the tagged section to load (type C). 


. Invoke the Initialize function (press F10). 


The editor reads the tagged section from the TOOLS.INI file. 


Insert the C header (press ALT+H). 


When the Microsoft Editor is started, the tagged sections are loaded in the following 


order: 


i 


Information specific to the operating system. . 

Depending upon the operating system you are working under, one of the follow- 
ing tagged sections is loaded (if present): 

¢ [M-3.20] (MS-DOS) 

© [M-10.0] (OS/2 protected mode) 

¢ [M-10.0R] (OS/2 real mode) 

This provides a way of automatically setting the vmbuf and maxmsg switches 
when running in protected mode. With the DOS version tag, you should insert 


the version number you are using. You can specify more than one version by 
using a tag like [M-3.20 M-3.30], which works with either version 3.20 or 3.30. 


. Information used for all editing sessions. 


All of the statements in the [M] section are loaded. 
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3. Information specific to the display. 


Depending on the video display you are using, one of the following tagged sec- 
tions is loaded (if present): 


[M-mono] 
[M-cga] 
[M-ega] 
[M-vga] 
[M-viking] 


You can also put statements for setting the screen dimensions and colors in these 
tagged sections, 
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Chapter 8 
Programming C Extensions 


C extensions offer the most powerful technique for customizing the Microsoft Editor. 
The term “C extension” refers to a C-language module containing new editing func- 
tions that you program. The module can also define new switches. Your functions can 
be attached to a key, given arguments, and used in macros just as intrinsic editing func- 
tions are. Any switches that you define can be set just as intrinsic editing eyitenes are, 
and your switches can be used by the functions you define. 


If you already understand the C programming language, you do not need to learn a 
new, specialized language to build your functions. C extensions let you use the full 
power of the C language: data structures, control-flow structures, and C operators. 
Furthermore, the C-generated code is compiled, not interpreted. Therefore your func- 
tions are fast. 


Note 


This chapter assumes that you already know how to program in C. Before you 
read the chapter, make sure that you understand the following C-language 
programming concepts: functions, pointers, structures, and unions. You also need 
to know how compile and link a C source file. 


You can also write extensions with MASM if you simulate the C memory model 
specified in Section 8.5.1, “Compiling in Real Mode.” However, this chapter is 
primarily addressed to C programmers. 


This chapter develops C-extension concepts gradually. The first time you read the 
chapter, you should read the sections in sequential order: 


¢ Requirements 
® How C extensions work 
e Writing the C extension 


® How to use the low-level editing functions 
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Compiling and linking 


A C-extension sample program 


8.1 Requirements 


To create C extensions, you need to have the following files and software present in 
your current directory (or directories listed in the PATH or INCLUDE environment 
variables, as appropriate): 


The Microsoft C Optimizing Compiler, Version 4.0 or later 


The Microsoft Overlay Linker, Version 3.60 or later, or the OS/2 version of the 
linker, or the Microsoft Segmented-Executable Linker Version 5.01 


EXTHDR.OBJ (supplied with the editor) 
EXT.H (supplied with the editor) 


SKEL.C (a template that you can replace with your own code) 


You need a minimum of 150K of available memory for the editor to load a C extension 
at run time. 


8.2 


How C Extensions Work 


A C-extension module is similar in the following respects to an OS/2 or Windows 
dynamic-link library: 


68 


There is no function called main in your module. Instead, you use certain names 
and structures that the editor recognizes. 


You compile and link to create an executable file, but this executable file is sepa 
rate from the main program, M.EXE. 


The editor loads your executable file into memory at run time. The editor uses a 
table-driven method for enabling your module to call functions within M.EXE. 
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Once your executable file is loaded, it resides in memory along with M.EXE. The edi- 
tor can call your functions, and your functions can call the Microsoft Editor’s low- 
level functions that perform input and output. 


The following list summarizes the overall process of developing and using a C 
extension: 


l. 


Compile a C module with a special memory-model option, then link the 
resulting object file to create an executable file. 


You also link in the object file EXTHDR.OBJ to the beginning of your execu- 
table file. This object file contains a special table that enables your functions to 
call functions within the editor effectively. 


. Start up the Microsoft Editor. Set the internal load switch to look for the 


executable file you created. (As discussed in Chapter 7, the load switch can be 
set in the TOOLS.INI file or manually with the Assign function). 


The editor loads your executable file into memory. 


. As soon as the executable file is loaded, the editor calls the function 


WhenLoaded, which is a special function that your module must define. 


At the same time, the editor examines the table cmdTable, which is an array of 
structures that your module must declare. The editor examines this table in order 
to recognize the editing functions that you have created. The table contains func- 
tion names and pointers to functions. 


. You can assign keys to call your functions. Assign a key manually or in the 


WhenLoaded function, then press the assigned key. You can also call an editing 
function indirectly by placing it in a macro and calling the macro. 


. When you invoke a C-extension function, the editor responds by calling your 


module. 


. Your editing function is executed. It calls the Microsoft Editor’s low-level 


functions in order to read from the text file, output to the text file, and print 
messages. 
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8.3. Writing a C Extension 


To create a successful C extension, you need to follow these guidelines: 


1. Check the README.DOC file to see what functions you can call from the 
standard C run-time library. 


A technical problem prevents library compatibility: to work with the Microsoft 
Editor, you must compile with SS not equal to DS. (The C compiler gives your 
module its own default data area, but your module shares the editor’s stack. 
Therefore your stack-segment and data-segment registers are not equal.) Since 
standard Microsoft C libraries assume SS equal to DS, you cannot use some Ii- 
brary functions. 


2. Include the file EXT.H. 


This file declares all the structures and types that are required to establish an in- 
terface to the editor. 


3. Include the standard items that are described in Section 8.3.1, “Required 
Objects.” Then compile and link as directed in Section 8.5, “Compiling and 
Linking.” 

8.3.1 Required Objects 


A C-extension module must have at minimum three items with the names given below: 


Object Name Description 

swiTable An array of structures that declares internal switches that 
you wish to create 

cmdTable An array of structures that declares editing functions that 
you have coded 

WhenLoaded A function that the editor calls as soon as the C-extension 


module is loaded 


Each of these items can be as short or as long as you wish. Each table can be as short 
as a single row of entries. The WhenLoaded function can return immediately, or it 
can perform useful initialization tasks such as assigning keys to functions or printing a 
message. 
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8.3.2 The Switch Table 


The switch table, swiTable, consists of a series of structures, in which each structure 
describes a switch you wish to create. The table ends with a structure that has all null 
(all zero) values. Though you may choose not to create any switches, the table must 
still be present. The simplest table allowed is therefore 


struct swibdesc swiTable[] = 


{ 
{ NULL, NULL, NULL } 


Me 


The structure type swiDesc is defined in EXT.H. This structure contains the following 
three fields that define a switch for the editor to recognize: 


1. A pointer to the name of the switch. 


2. A pointer to the switch itself or to a function. If the switch is Boolean, then this 
field must point to the switch (an integer which assumes the value —1 or 0). If 
the switch is text, then this field must point to a function, as explained below. 
If the switch is numeric, then this field points to either an integer or to a 
function, depending on the value of the third field. 


3. A flag that indicates the type of switch: either SWI_BOOLEAN, 
SWI_NUMERIC, or SWI_SPECIAL. 


If the third field has value SWI_SPECIAL, then the second field must be a pointer to 
a function of type int pascal. You define this function in your code. Each time the 
value of the switch changes, the editor calls your function and passes the updated 
value in a character string. Your function should declare exactly one parameter: a far 
pointer to a character. 


The table may have any number of rows (each row being a structure), and must at least 
include the final row of all null values. Here is an example of a table that creates a 
numeric switch with a default value of 27: 


int n = 27; 
struct swiDesc swiTable [] = 
{ 


{ "newswitch", &n, SWI NUMERIC } , 
{ NULL, NULL, NULL } 
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8.3.3. The Command Table 


The command table, cmdTable, is similar to the table swiTable in its construction. 
Each “row” of the table consists of a structure that describes an editing function 
that you want the editor to recognize. The last row must contain all null values. The 
simplest table allowed is the following: 


struct cmdDesc cmdTable[] = 


{ 
{ NULL, NULL, NULL, NULL } 


} 


Usually you will want to declare at least one new editing function. The structure type 
cmdDesc is defined in EXT.H. This structure contains the following four fields that 
make an editing function recognizable to the editor: 


1. A pointer to the name of the function as it will be used within the editor. This 
name could appear in assignments and macros. 


2. The address of the function itself. Give the function name, but do not follow it 
with parentheses. 


3. A field used internally by the editor. Always declare this field as null. 


4. The type of the function. Function types are described below and define what 
type of argument the function will accept. 


Here is an example of a command table that declares a function that takes no 
arguments: 


struct cmdDesc cmdTable[] = 


{ 
{ "newfun", newfun, NULL, NOARG } , 
{ NULL, NULL, NULL, NULL } 


} 


In the fourth field of the command table, use one or more of the values described 
below: 


Value Description 


KEEPMETA Does not take the Meta prefix. The function re- 
serves Meta for next function. 


CURSORFUNC Executes cursor movement only. Highlighting 


and the Arg function are not affected. The func- 
tion does not take arguments. 
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WINDOWFUNC 


NOARG 
TEXTARG 


BOXSTR 


NULLARG 


NULLEOL 


NULLEOW 


LINEARG 


STREAMARG 


BOXARG 


NUMARG 


MARKARG 
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Window-movement function. Highlighting is not 
affected. 


Accepts absence of Arg prefix. 
Accepts a text argument. 


Accepts a one-line box argument (in other 
words, a streamarg). The string of text 
highlighted is passed as a text argument. 


Accepts Arg without requiring an argument. 


Accepts Arg without requiring an argument. The 
function is passed pointer to textarg consisting 
of an ASCIIZ string from the cursor to the end of 
the line. 


Accepts Arg without requiring an argument. The 
function is passed pointer to textarg consisting 
of an ASCIIZ string from the cursor to the end of 
the word (next white space). 


Accepts a linearg. If the editor detects a linearg, 
function is passed the beginning line of the range 
and the ending line of the range. 


Accepts any kind of cursor movement. The func- 
tion is passed the beginning point of the range 
and the ending point of the range. 


Accepts a boxarg. If the editor detects a boxarg, 
the function is passed the line and column bound- 
aries of the region. 


Accepts a numarg. Information is passed as a 
linearg; in other words, the function is passed a 
range of lines. 


Accepts a markarg. Information is passed as a 
streamarg; in other words, the function is passed 
beginning and ending point of range defined by 
the cursor position and the marker. 
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In the descriptions above, the term “ASCTIZ string” refers to a string of characters ter- 
minated by a zero (or null) byte. The descriptions also refer to the passing of informa- 
tion to the function; you’ll see how the function receives information in Section 8.3.5, 
“Writing the Editing Function.” 


You can combine the function types with binary or (| ). For example, you can specify 
a function that accepts a boxarg, linearg, or numarg as: 


BOXARG | LINEARG | NUMARG 


8.3.4 The WhenLoaded Function 


The function WhenLoaded takes no arguments and can return immediately if you 
want. However, you must include the function because the editor expects it to be pre- 
sent. The simplest version of WhenLoaded is: 


WhenLoaded () 
{ 


recurn; 


} 


In Section 8.4, “Calling Low-Level Editing Functions,” you'll learn how to call func- 
tions that assign keys to functions and print a message on the message line. These 
functions are often useful to call from within WhenLoaded. 


8.3.5 Writing the Editing Function 


This section describes how to declare an editing function and how to use information 
that is passed to the function from the editor. The editing function must return type 
flagType, which is an integer that takes values true (—1) or false (0) and is defined in 
the file EXT.H. Editing functions are declared with Pascal calling conventions and 
must be of type EXTERNAL. The sample function Ske1 is declared as follows: 


#define TRUE -1 
#define FALSE Q 


flagType pascal EXTERNAL Skel (argData, pArg, fMeta) 
unsigned int argData; 

ARG far *pArg; 

flagType fMeta; 

{ 

return TRUE; 

} 
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The parameter list is described below: 
Parameter Description 


argData The value of the keystroke used to invoke the function. This 
parameter is generally not used. 


pArg A pointer to a structure that contains almost all the informa- 
tion passed by the editor. This structure is discused in detail 
below. 


fMeta An integer that describes whether or not a Meta prefix is pre- 
sent. This integer has value true (~1) if Meta is present, and 
value false (0) if not. 


The parameter pArg points to a structure whose first element is always argType. The 
argument type returned in this structure uses the same values listed in Section 8.3.3, 
“The Command Table.” Thus, you could test for the presence of a numarg with the fol- 
lowing code: 


if (pArg->argType == NUMARG) { 


/* take appropriate action for numarg */ 


} 


The rest of the structure consists of a union of structures. The C data-type union is nec- 
essary here; it enables the editor to pass data in a variety of different formats. The 
exact format depends on which member of the union 1s used. In any case, the data is 
passed to the same area of memory. 


The declaration of the ARG structure in the file EXT.H is as follows: 


struct argType { 
aT argType; 


union { 
struct noargType noarg; 
struct textargType textarg; 
struct nullargType nullarg; 
struct lineargType linearg; 
struct streamargType streamarg; 
struct boxargType boxarg; 

} arg; 


} 


typedef struct argType ARG; 
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The editor uses one of the structures in the union to return information about argu- 
ments. The choice of structures depends on the type of argument. For example, if the 
argType element is equal to LINEARG, the editor returns information in the structure 
pArg->arg.linearg. 


Consult the file EXT.H to see how each structure is declared. For example, the textarg 
structure type is declared as follows: 


struct textargType { 
a cArg; 
LINE y; 
COL Xx; 
char far *pText; 
} 


In the structure above, cArg contains an integer equal to the number of times Arg was 
invoked. The variables y and x are integers that give the cursor position, and pText 
points to the actual string text. The following code initializes variables row and col, 
and copies the textarg into a buffer: 


LINE row; 
COL col; 
Lat 14 


char far *p, buffer[{81]; 


row = pArg->arg.textarg.y; 

col = pArg->arg.textarg.x; 

p = pArg->arg.textarg.pText; 

for (i = 0; {c = *p) != NULL; i+t) 
buffer[i] = c; 


In another example, if pArg->argType is equal to type NULLARG, then you can 
initialize row and col as follows: 


LINE row; 
COL, "Soi; 


row = pArg->arg.nullarg.y; 
col = pArg->arg.nullarg.x; 


8.3.6 Putting It All Together 


Here is a listing of the source module SKEL.C, which provides you with the basic tem- 
plate of a C extension. This code does nothing, but it is recognized by the Microsoft 
Editor as logically correct. You can makes use of this template by using your own func- 
tion names and inserting your own statements. Before you can write useful code, 
however, you first need to read Section 8.4, “Calling Low-Level Editing Functions.” 
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#include "ext.h" 


#define TRUE -1 
#adefine FALSE 0 
#define NULL ((char *) 0) 


flagType pascal EXTERNAL Skel (argData, pArg, fMeta) 
unsigned int argData; 

ARG far *pArg; 

flagType fMeta; 


{ 
return TRUE; 


} 


struct swiDesc swiTable[] = { 
{ NULL, NULL, NULL } 


be 


struct emdDesc cmdTable[jJ = { 
{ "skel™, Skel, 0, NOARG } , 
{ NULL, NULL, NULL, NULL } 

be 


WhenLoaded (} 


{ 
return TRUE; 


} 


8.4 Calling Low-Level Editing Functions 


The functions presented in this section cannot be called directly by the user. However, 
they can be called by higher-level editing functions to carry out specific tasks such as 
reading a line from a file, replacing or inserting a character, printing messages, and 
deleting or inserting text. These functions are used within the Microsoft Editor itself 
and are made available to be called by functions in a C extension. 


Note 


All pointers that you pass (such as character pointers) need to refer to data that are 
declared externally; in other words, do not pass pointers to strings that you declare 
locally. Because SS does not equal DS, the low-level function will not properly 
find stack data, such as a local (or “automatic”) variable. 
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This section serves as a guide to the most commonly used low-level functions. You can 
begin writing C extensions by using the functions presented here. Later you can con- 
sult the file EXT.DOC for a complete listing of all low-level functions. 


Sections 8.4.1-8.4.3 present groups of functions by covering the following topics: 
® Reading from a file 
® Writing toa file 


® Initialization functions 


8.4.1 Reading from a File 


This section presents functions that you can call to scan a file (either the current file or 
any other that you specify). 


8.4.1.1 The FileNameToHandle Function 


To read or write to a file (including the current file), you must first call the 
FileNameToHandle function, which returns a handle to the named file. The function 
is declared as follows: 


PFILE pascal FileNameToHandle (pname, pShortName) 
char *pname, *pShortName; 


The pname parameter points the file name. If pname points to a zero-length string, 
then the function returns a handle to the current file. Unless pShortName is a null 
pointer, the editor searches its list of current files (files that have been edited in this 
session) for a path name that includes the name pointed to by pShortName. If there is a 
match, the function uses the full path name found. 


For example, the following code returns a handle to the current file: 
PFILE curfile; 


curfile = FileNameToHandle("", NULL); 
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8.4.1.2 The GetLine Function 


The GetLine function provides the principal means for reading text from a file. 


int pascal GetLine (Jine, buf, pfile) 
LINE /ine; 

char far *buf 

PFILE pfile; 


The function reads a specified line of text, and copies the line into a character-string 
buffer pointed to by buf. The line parameter is an integer that contains a line number. 
The pfile parameter 1s a pointer returned by FileNameToHandle. 


The following example reads the line of text which includes the initial cursor position: 


PFILE cfile; 
char buffer[256]; 


cfile = FileNameToHandle("", NULL); 
GetLine(pArg~->arg.nullarg.y, buffer, cfile) 


8.4.1.3 The FileLength Function 


The FileLength function is useful for doing global file operations, in which you need 
to know when you are at the last line. The function takes a pointer to a file handle as 
input, returns an integer, and is declared as follows: 


LINE pascal FileLength (pFile) 
PFILE pfile; 


The following example stores the length of the current file in the variable n: 


n = FileLength (cfile); 


8.4.2 Writing toa File 


This section presents functions that are useful for altering a file by replacing, inserting, 
or deleting text. 
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8.4.2.1 The Replace Function 


The Replace function inserts or replaces characters one at a time; it is declared as 
follows: 


flagType pascal Replace (c, x, y, pFile, ffnsert) 
char c; 

COL x; 

LINE jy; 

PFILE pFile; 

flagType Insert; 


The c parameter contains the new character. The x and y parameters indicate the file 
position, by column and line, where the edit is to take place. The pFile parameter is a 
file handle returned by the FileNameToHandle function. To specify insertion, set 
finsert to true (-1). To specify replacement, set ffnsert to false (0). The function returns 
true (—1) if the edit is successful. 


For example, the following code inserts the word “Hello” at line y and column x of 
the current file: 


#define TRUE -l 
char RD | 
PFILE cfile; /* handle to current file */ 


cfile = FileNameToHandle("", NULL); /* initialize cfile */ 
for (p = "Hello"; *p: ptt+, yt+) 
Replace(*p, x, y, cfile, TRUE); 


8.4.2.2 The PutLine Function 


The PutLine function replaces a line of text; it is declared as follows: 


void pascal PutLine (line, buf, pfile) 
LINE line; 

char far *buf; 

PFILE pfile; 


The parameter buf points to the string that contains the new line of text. This string 
should terminate with a null value, but it should not contain a new-line character. The 
editor takes care of inserting a new-line character at the proper position in the file. The 
parameter /ine contains the line number at which the replacement it to take place. Line 
numbers start at 0; if /ine has the value 0 then the new line of text is inserted at the 
beginning of the file. 
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The following code replaces the first line of the current file with the string pointed to 
by buffer: 


[PuthLine (0, buffer, cfile); 


8.4.2.3. The CopyLine Function 


The CopyLine line function can be used either to copy a group of lines from one area 
to another or to insert a blank line. The function is declared as follows: 


void pascal CopyLine (pFileSrc, pFileDst, yStart, yEnd, yDst) 
PFILE pFileSrc, pFileDst; 
LINE yStart, yEnd, yDst; 


The pFileSrc and pFileDst parameters are file handles. If pFileSrc is null (Q), then the 
function inserts a blank line. Otherwise, the function inserts lines from yStart to yEnd. 
Lines are inserted directly before yDst. For example, the following code inserts a blank 
line at the beginning of the file: 


CopyLines(NULL, cfile, NULL, NULL, 0); 


8.4.2.4 The DelStream Function 


The DelStream function deletes a stream of text beginning with a starting coordinate 
and going up to but not including the ending coordinate. The function is declared as 
follows: 


void pascal DelStream (pfile, xStart, yStart, xEnd, yEnd) 
PFILE pfile; | 

COL xStart, xEnd 

LINE yStart, yEnd; 


The xStart and yStart parameters are the beginning coordinates; the xEnd and yEnd par- 
ameters are the ending coordinates. The coordinates are all integers. 


The following example deletes the stream of text beginning with line 2 column 3, up to 
but not including line 5 column 4. 


DelStréam. (cfiilke;,.3,2;47;5)3 
8.4.3 Initialization Functions 


The low-level functions in this section are typically called by the WhenLoaded func- 
tion, but they can be called by editing functions as well. 
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8.4.3.1 The SetKey Function 


The SetKey function assigns an editing function to a key, and is declared as follows: 


flagType pascal SetKey (name, p) 
char far *name, far *p; 


The name parameter points to a string containing the name of the function, and the p 
parameter points to a string that names the key. The rules for naming the key are the 

same as those given in Chapter 6, “Function Assignments and Macros.” The function 
returns true (—1) if the assignment is successful. 


The following code assigns the CTRL+X key to the newly defined function NewFunc: 


SetKey("NewFunc", "ctrl+x"); 


8.4.3.2 The DoMessage Function 


The DoMessage function outputs a message on the dialog line and returns the number 
of characters written. 


int pascal DoMessage (pStr) 
char far *pStr; 


The pSir parameter points to the message you want to write. 
The following example outputs a message on the dialog line: 


DoMessage("Hello, world."); 


8.4.3.3. The BadArg Function 


The BadArg function reports an error message stating that the user’s argument was 
not accepted. Note that usually you do not need to call this function because the 

editor looks at the type of your function as declared in cmdDesc (TEXTARG, 
STREAMARG, and so forth) and rejects commands with the wrong type of argument. 
The function is declared as follows: 


flagType pascal BadArg (void) 
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8.5 Compiling and Linking 


After you’ve written your C module following the guidelines in the last few sections, 
you’re ready to compile and link. The procedures for compiling and linking in pro- 
tected mode are slightly different from compiling and linking in real mode. Sections 
8.5.1—8.5.2 consider both environments. 


8.5.1 Compiling in Real Mode 
To create a C extension for real mode, follow these two steps: 


1. Compile with command line options /Gs and /Asfu. These options establish the 
proper memory model and calling convention, and are mandatory. (If you are 
programming in MASM, use near code and far data segments, in which SS is 
not assumed equal to DS.) For example: 


CL /c /Gs /Asfu myext.c 


2. Link with the command-line options /NOD and /NOI. Linking with /NOD is 
important because it prevents the linker from linking in standard libraries. 
Always link the file EXTHDR.OBJ first. For example: 


LINK /NOI /NOD exthdr.obj myext.obj, myext; 
When you use the CL driver, you can accomplish both steps in one command line: 
CL /Gs /Asfu /Femyext exthdr myext.c /link /NOD /NOI 


When you correctly compile and link your C-extension module, you produce an execu- 
table file. You cannot execute this file directly from DOS. However, the Microsoft Edi- 
tor can load the file into memory and use the functions that your module defines. 
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To use the C extension, make sure that your executable file 1s in the current directory 
or in a directory listed in the PATH environment variable. After you start up the Micro- 
soft Editor, set the load switch to make the editor load your C extension. For example, 
after you have created the file MYEXT.EXE, you could place the following statement 
in the TOOLS.INI file: 


load:imyext.exe 


The editor responds by automatically loading your C-extension module into memory 
whenever the editor checks the TOOLS.INI file for initialization. 


8.5.2 Compiling in Protected Mode 


To compile and link a protected-mode C extension, follow the instructions above for 
real mode, except in two respects: 


1. Use the /G2 and /Lp options when you compile. (The /Lp option is not required 
unless you compile a protected-mode application from within real mode.) The 
example in the previous section would therefore change to 


CL /c /Gs /Asfu /G2 /Lp myext.c 


2. Instead of linking to produce an executable file, you link to produce a .DLL file 
(a dynamic-link application). Specify SKEL.DEF as the module-definition file, 
and place the resulting .DLL file in one of the directories listed in the 
LIBPATH directive in your CONFIG.SYS file. You may want to edit the 
SKEL.DEF file, to change the library name specified. 


8.6 A C-Extension Sample Program 


The following C-extension sample program features one simple function named 
Upper, which accepts a simple streamarg or textarg. (As explained earlier in the chap- 
ter, the BOXSTR function type accepts a one-line stream of text highlighted on the 
screen.) The function responds by replacing characters in the file, beginning at the cur- 
sor position, with characters from the textarg that have been converted to uppercase 
letters. 
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#include "ext.h" 
#define TRUE -1l 
#define FALSE 0 
#define NULL {((char *) Q) 


flagType pascal EXTERNAL Upper (argData, pArg, fMeta) 
unsigned int argData; 

ARG far *pArg; 

flagType fMeta; 

{ 


LINE row; /* coordinates in file */ 

COL col; 

ale gh aan /* replacement character */ 

char far *p; /* pointer to textarg */ 

PFILE cfile; /* pointer to file handle */ 

cfile = FileNameToHandle("™", NULL) /* get current file */ 
row = pArg->arg.textarg.y; /* load coordinates */ 


col = pArg~>arg.textarg.x; 
p = pArg->arg.textarg.pText; 


fOr. ("OP prt: COlr+). 4 /* for each char in textarg */ 
c = *p; /* get character */ 
lf (c >= 'a’ && c <= '2") /* convert to upper */ 
Git] -7 A = * a? 


Replace. (ce; col, row, ciile, FALSE); /* put in file *7 
} 
return TRUE; 
} 


struct swiDesc swiTable [] = { 
{ NULL, NULL, NULL } 
be 


struct cmdDesc cmdTable [] = { 
{ "Upper”, Upper, 0, BOXSTR | TEXTARG }, 
{ NULL, NULL, NULL, NULL } 

? 


WhenLoaded () 


{ 
SetKey("Upper", "altt+u"); 
DoMessage ("Upper function now loaded."); 
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Reference Tables 


A.1 Categories of Editing Functions 


Table A.1 lists the editing functions by category and gives a brief description of each 
function. 


Table A.1 

Summary of Editing Functions by Category 

Cursor Movement Description 

Backtab Moves cursor left to previous tab stop 
Begline Moves cursor left to beginning of line 
Down Moves cursor down one line 

Endline Moves cursor to right of last character of line 
Home Moves cursor to upper-left corner of window 
Left Moves cursor left one character 

Mark Moves cursor to specified position in file 
Mlines Moves cursor back by lines 

Mpage Moves cursor back by pages 

Mpara Moves cursor back by paragraphs 

Mword Moves cursor back by words 

Newline Moves cursor down to next line 

Plines Moves cursor forward by lines 

Ppage Moves cursor forward by pages 

Ppara Moves cursor forward by paragraphs 
Pword Moves cursor forward by words 

Restcur Restores cursor position saved with Savecur 
Right Moves cursor right one character 

Savecur Saves cursor position for use with Restcur 
Tab Moves cursor right to next tab stop 

Up Moves cursor up one line 
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~ Table A.1 (continued) 


Windows 


Setwindow 
Window 


Searching/Replacing 


Msearch 
Psearch 
Qreplace 
Replace 


Moving/Copying Text 


Copy 
Ldelete 
Paste 
Sdelete 


Inserting/Deleting Text 


Cdelete 
Curdate 
Curday 
Curfile 
Curfileext 
Curfilenam 
Curtime 
Curuser 
Emacscdel 
Emacsnewl 
L delete 
Linsert 
Pbal 
Sdelete 


Sinsert 


Description 


Redisplays window 
Creates, removes, and moves between windows 


Description 


Searches backward 

Searches forward 

Replaces with confirmation 
Replaces without confirmation 


Description 


Copies lines into the Clipboard 
Deletes lines into the Clipboard 
Inserts text from the Clipboard 
Deletes stream of text, including line breaks 


Description 


Deletes character to left, excluding line breaks 
Inserts current date (e.g. 27-Jun-1987) 

Inserts current day (Sun...Sat) 

Inserts name of current file 

Inserts extension of current file 

Inserts base name of current file 

Inserts current time (e.g. 13:45:55) 

Inserts current user name 

Deletes character to left, including line breaks 
Starts new line, breaking current line 

Deletes lines into the Clipboard 

Inserts blank lines 

Balances parentheses and brackets 

Deletes stream of text, including line breaks 
Inserts blanks, breaking lines if necessary 


Table A.1 (continued) 
File Operations 


Argcompile 
Compile 
Refresh 
Setfile 


Miscellaneous 


Arg 

Assign 
Cancel 
Execute 
Exit 

Help 
Information 
Initialize 
Insertmode 
Lasttext 
Quote 
Shell 

Undo 


Reference Tables 


Description 
Performs the Arg Compile command 


Performs compilation and reviews error messages 
Rereads file, discarding edits 
Switches to alternate file 


Description 


Introduces an argument or function 
Assigns value to a configuration variable 
Cancels current operation 

Executes an editor function 

Exits the editor 

Displays current key assignments 
Displays information about an editing session 
Rereads initialization file 

Toggles insert mode on and off 

Recalls the last textarg entered 

Treats next character literally 

Runs the command shel] 


Reverses the effect of the last editing change 
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A.2. Key Assignments for Editing Functions 


Table A.2 lists the editing functions and the assigned keys for each of the configura- 
tions provided with the setup program. 


Table A.2 
Function Assignments 
Quick/ 
Function Default WordStar BRIEF EPSILON 
Arg ALT+A ALT+A ALT+A CTRL+U or 
CTRL+X 
Argcompile F5 F5 ALT+F10 F5 
Assign ALT+= ALT+= | F7 Fl 
Backtab SHIFT+TAB SHIFT+TAB SHIFT+TAB SHIFT+TAB 
Begline HOME HOME or HOME CTRL+A 
CTRL+QS 
Cancel ESC ESC ESC CTRL+C 
Cdelete CTRL+G CTRL+G BKSP a 
Compile SHIFT+F3 SHIFT+F3 CTRL+N SHIFT+F3 
Copy CTRL+INS CTRL+INS + (keypad) ALT+W 
or press + 
(keypad) 
Curdate ae oe aoe an8 
Curday — bee --- ae 
Curfile a a-- eat oa 
Curfileext a --- --- slate 
Curfilenam a+ --- aoe wie 
Curtime = =. eee ae 
Curuser =e _ ude ists 
Down DOWN or DOWN or DOWN DOWN or 
CTRL+X CTRL+X | CTRL+N 
Emacscdel BKSP BKSP --- BKSP or 
CTRL+H 
Emacsnewl ENTER ENTER --- ENTER 
Endline END END or END CTRL+E 
CTRL+QD 


Table A.2 (continued) 

Function Default 

Execute F7 

Exit F8 

Help Fl 

Home CTRL+HOME 

Information SHIFT+F1 

Initialize SHIFT+F8 

Insertmode INS or CTRL+V 

Lasttext CTRL+0 

Ldelete CTRL+Y 

Left LEFT or CTRL+S 

Linsert CTRL+N 

Mark CTRL+M 

Meta F9 

Mlines CTRL+W 

Mpage PGUP or CTRL+R 

Mpara CTRL+PGUP 

Msearch F4 

Mword CTRL+LEFT or 
CTRL+A 

Newline --- 

Paste SHIFT+INS 

Pbal CTRL+[ 

Plines CTRL+Z 

Ppage PGDN or 
CTRL+C 

Ppara CTRL+PGDN 

Psearch F3 

Pword CTRL+RIGHT 
or CTRL+F 

Qreplace CTRL+\ 

Quote CTRL+P 


Quick/ 
WordStar 

F10 

ALT+X 

Fl 
CTRL+HOME 
SHIFT+F1 
ALT+F10 

INS or CTRL+V 
ALT+L 
CTRL+Y 

LEFT 

CTRL+N 
ALT+M 

F9 

CTRL+W 
PGUP or CTRL+R 
CTRL+PGUP 
F4 

CTRL+LEFT 


SHIFT+INS 
CTRL+[ 
CTRL+Z 


PGDN or 
CTRL+C 


CTRL+PGDN 
F3 


CTRL+RIGHT 
or CTRL+F 


ALT+F3 


ALT+Q 


BRIEF 


F10 

ALT+X 
ALT+H 
CTRL+HOME 
ALT+B 
SHIFT+F10 
ALT+I 
ALT+L 
ALT+D 

LEFT 
CTRL+ENTER 
ALT+M 

F9 

ALT+U 
PGUP 
CTRL+PGUP 
ALT+F5 
CTRL+LEFT 


ENTER 
INS 
CTRL+[ 
ALT+D 
PDGN 


CTRL+PDGN 
F5 
CTRL+RIGHT 


F6 


ALT+Q 


Reference Tables 


EPSILON 


ALT+X 

F8 

F10 

HOME 
SHIFT+F1 
ALT+F10 
CTRL+V 

ALT+L 

CTRL+K 

LEFT or CTRL+B 
CTRL+0 
CTRL+@ 

F9 

CTRL+W 

PGUP or ALT+V 
ALT+UP 
CTRL+R 


CTRL+LEFT or 
ALT+B 


CTRL+Y or INS 
CTRL+[ 
CTRL+Z 


PDGN or 
CTRL+V 


ALT+DOWN 
F4 or CTRL+S 


CTRL+RIGHT 
or ALT+F 


ALT+F3 or 
ALT+5 or ALT+8 


CTRL+Q 
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Table A.2 (continued) 
Quick/ 
Function Default WordStar BRIEF EPSILON 
Refresh SHIFT+F7 ALT+R F9 ALT+R 
Replace CTRL+L CTRL+L SHIFT+F6 --- 
Restcur --- --- ~~ --- 
Right RIGHT or RIGHT or RIGHT RIGHT or 
CTRL+D CTRL+D CTRL+F 

Savecur = --- — — 
Sdelete DEL DEL DEL or press — DEL or 

(keypad) CTRL+D or 

CTRL+W 

Setfile F2 F2 ALT+N F2 
Setwindow CTRL+} CTRL+] F2 CTRL+] 
Sheil SHIFT+F9 SHIFT+F9 ALT+Z ALT+Z 
Sinsert CTRL+J CTRL+INS CTRL+INS ALT+INS 
Tab TAB TAB TAB TAB or CTRL+I 
Undo ALT+BKSP ALT+BKSP * (keypad) CTRL+BKSP 
Up UP or CTRL+E UP or CTRL+E UP UP or CTRL+P 
Window F6 F6 Fl ALT+PGDN 
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A.3 Comprehensive Listing of Editing Functions 


Table A.3 gives a comprehensive listing of the editing functions and syntax for each 
command. Default keystrokes, if available, are given in parentheses. 


Table A.3 


Comprehensive List of Functions 


Function (and 
Default Keystrokes) 


Arg 
(ALT+A) 
Argcompile 
(F5) 
Assign 
(ALT+=) 


Backtab 
(SHIFT+TAB) 


Begline 
(HOME) 


Cancel 
(ESC) 


Syntax 


Arg 
Argcompile 


Arg Assign 


Arg boxarg Assign 


Arg linearg Assign 


Arg streamarg Assign 


Arg textarg Assign 


Arg ? Assign 


Backtab 


Begline 
Meta Begline 


Caricel 


Description 


Introduces a function or an ar- 
gument for a function. 


Performs the Arg Compile 
command. 


Treats the text from the initial 
cursor position to the end of the 
line (not including the line 
break) as a function assignment 
or macro definition. 


Treats each line of the boxarg 
as an individual function as- 
signment or macro definition. 


Treats each line as a separate 
function assignment or macro 
definition, ignoring blank lines. 


Treats the highlighted text as a 
function assignment or macro 
definition. 


Treats textarg as a function as- 
signment or macro definition. 


Displays the current function 
assignments for all functions 
and macros. 


Moves the cursor to the pre- 
vious tab stop. Tab stops are de- 
fined to be every nth character, 
where n is defined by the 
tabstops switch. 


Places the cursor on the first 
nonblank character on the line. 


Places the cursor in the first 
character position of the line. 


Cancels the current operation 
in progress. 
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Table A.3 (continued) 


Function (and 
Default Keystrokes) Syntax 


Cdelete Cdelete 
(CTRL+G) 


Compile Compile 
(SHIFT+F3) 


Meta Compile 


Arg Compile 


Arg streamarg Compile 
Arg textarg Compile 
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Description 


Deletes the previous character, 
excluding line breaks. If the 
cursor is in column 1, Cdelete 
moves the cursor to the end of 
the previous line. If issued in in- 
sert mode, Cdelete deletes the 
previous character, reducing 
the length of the line by 1; 
otherwise it deletes the pre- 
vious character and replaces it 
with a blank. If the cursor is 
beyond the end of the line 
when the function is invoked, 
the cursor is moved to the im- 
mediate right of the last 
character on the line. 


Reads the next error message 
and tries to parse it into file, 
row, column, and message. If it 
is successful, the editor reads in 
the file, places the cursor on the 
appropriate row and column, 
and displays the message on 
the dialog line. The utility 
MEGREP.EXE, Microsoft C, 
and the Microsoft Macro As- 
sembier generate output com- 
patible with this format. 


Reads error messages and ad- 
vances to the first message 
that does not refer to the cur- 
rent file. 


Compiles and links the current 
file. The command and argu- 
ments used to compile the file 
are specified by the extmake 
switch according to the exten- 
sion of the file. 


Compile and link the file 
specified by streamarg or 
textarg. The command and 
arguments used to compile 
the file are specified by the 
extmake switch according to 
the extension of the file. 


Table A.3 (continued) 


Function (and 
Default Keystrokes) 


Copy 
(CTRL+INS, or press + 
on keypad) 


Curdate 


Syntax 


Arg Arg streamarg Compile 
Arg Arg textarg Compile 


Arg Meta Compile 


Copy 


Arg Copy 


Arg boxarg Copy 
Arg linearg Copy 
Arg streamarg Copy 
Arg textarg Copy 


Arg numarg Copy 


Arg markarg Copy 


Curdate 


Reference Tables 


Description 


Invoke the specified text as a 
program. The program is as- 
sumed to display its errors in 
the following format: 


file row column message 


This is often used to find a par- 
ticular text pattern in a series of 
files by using MEGREP.EXE. 


See Appendix B, “Support Pro- 
grams for the Microsoft Edi- 
tor,” for more information. 


Backs up to display the pre- 
vious message, up to a maxi- 
mum number of messages 
specified by the maxmsg 
switch. 


Copies the current line into the 
Clipboard. 


Copies text from the initial cur- 
sor position to the end of the 
line and places it into the 
Clipboard. Note that the line 
break is not picked up. 


Copy the specified text into the 
Clipboard. 


_ Copies the specified number 


of lines into the Clipboard, 
starting with the current line. 


Copies the range of text be- 
tween the cursor and the loca- 
tion of the file marker into the 
Clipboard. The copied text is 
treated as a streamarg, boxarg, 
or linearg depending on the 
relative positions of the initial 
cursor position and the file- 
marker location. 


Inserts the current date at the 
cursor in the format of Jun-27- 
1987. 
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Table A.3 (continued) 
Function (and 
Default Keystrokes) Syntax 
Curday Curday 
Curfile Curfile 
Curfileext Curfileext 
Curfilenam Curfilenam 
Curtime Curtime 
Curuser Curuser 
Down Down 
(DOWN or CTRL+X) 

Meta Down 
Emacscdel Emacscdel 
(BKSP) 
Emacsnewl Emacsnewl 
(ENTER) 
Endline Endline 
(END) 
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Description 


Inserts the current day at the 
cursor in the format of 
Sun...Sat. 


Inserts the fully-qualified 
pathname of the current file at 
the cursor. 


Inserts the extension of the cur- 
rent file at the cursor. 


Inserts the base name of the cur- 
rent file at the cursor. 


Inserts the current time at the 
cursor in the format of 
13:45:55. 


Inserts the name of the current 
user, using the MAILNAME 
environment variable, at the 
cursor. 


Moves the cursor down one 
line. If this would result in the 
cursor moving out of the win- 
dow, the window is adjusted 
downward by the number of 
lines specified by the vscroll 
switch or less if in a small 
window. 


Moves the cursor to the bottom 
of the window without chang- 
ing the column position. 


Performs similarly to Cdelete, 
except that at the beginning of 
a line while in insert mode, 
Emacscdel deletes the line 
break between the current line 
and the previous line, joining 
the two lines together. 


Performs similarly to Newline, 
except that when in insert 
mode, it breaks the current line 
at the cursor position. 


Moves the cursor to the imme- 
diate right of the last nonblank 
character on the line. 


Function (and | 


Execute 
(F7) 


Exit 
(F8) 


Help 
(Fl) 


Home 
(CTRL+HOME) 


Information 
(SHIFT+F1) 


Table A.3 (continued) 


Default Keystrokes) 


Syntax 


Meta Endline 


Arg Execute 


Arg linearg Execute 
Arg streamarg Execute 
Arg textarg Execute 


Exit 


Meta Exit 


Arg Exit 


Arg Meta Exit 


Help 


Home 


Information 


Reference Tables 


Description 


Moves the cursor one character 
beyond the column correspond- 
ing to the rightmost edge of the 
window. 


Treats the line from the initial 
cursor position to the end as a 
series of Microsoft-Editor com- 
mands and executes them. 


Treat the specified text as 
Microsoft-Editor commands 
and execute them, similar to 
the way macros operate. 


Saves the current file. If multi- 
ple files were specified on the 
command line, the editor ad- 
vances to the next file. Other- 
wise the editor quits and re- 
turns control to the operating 
system. 


Performs similarly to Exit, ex- 
cept that the current file is not 
saved, 


Performs similarly to Exit, ex- 
cept that if multiple files are 
specified on the command line, 
the editor exits without advanc- 
ing to the next file. 


Performs similarly to Arg Exit, 
except that the editor does not 
save the current file. 


Lists the editing functions and 
current key assignments. 


Places the cursor in the upper- 
left corner of the current 
window. 


Saves the current file and 
Setfiles to an information file 
that contains a list of all files in 
memory along with the current 
set of files that you have 
edited. The size of this list is 
controlled by the tmpsav 
switch, which has a default 
value of 20. 
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Table A.3 (continued) 

Function (and 

Default Keystrokes) Syntax 

Initialize Initialize 

(SHIFT+EF8) 
Arg Initialize 
Arg streamarg Initialize 
Arg textarg Initialize 

Insertmode Insertmode 

(INS or CTRL+V) 

Lasttext Lasttext 

(CTRL+0) 

L delete Ldelete 

(CTRL+Y) 
Arg Ldelete 
Arg boxarg Ldelete 
Arg linearg Ldelete 
Arg streamarg Ldelete 
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Description 


Reads all the editor statements 
from the [M] section of 
TOOLS.INI 


Reads the editor statements 
from the TOOLS.INI file, 
using the continuous string of 
nonblank characters, starting 
with the initial cursor position, 
as the tag name. 


Read all the editor statements 
from the [M] section and the 
[M-streamarg] or [M-textarg] 
section of TOOLS.INI. 


Toggles the insert-mode 
switch. The status of the insert- 
mode switch can be seen on the 
status line; if insert mode is on, 
insert appears on the status 
line. While in insert mode, 
each character that is entered is 
inserted at the cursor position, 
shifting the remainder of the 
line one position to the right. 
Overtype mode replaces the 
character under the cursor with 
the one that is entered. 


Recalls the last textarg. This 

function is the same as invok- 
ing the Arg function and then 
retyping the previous fextarg. 


Deletes the current line and 
places it into the Clipboard. 


Deletes text, starting with the 
initial cursor position through 
the end of the line, and places it 
into the Clipboard. Note that it 
does not join the current line 
with the next line. 


Delete the specified text from 
the file and place it into the 
Clipboard. 


Table A.3 (continued) 


Function (and 
Default Keystrokes) 


Left 
(LEFT or CTRL+S) 


Linsert 
(CTRL+N) 


Mark 
(CTRL+M) 


Syntax 


Meta Left 


Linsert 


Arg Linsert 


Arg boxarg Linsert 
Arg linearg Linsert 
Arg streamarg Linsert 
Mark 


Arg Mark 


Arg numarg Mark 


Arg Arg textarg Mark 


Reference Tables 


Description 


Moves the cursor one character 
to the left. If this would result 
in the cursor moving out of the 
window, the window is ad- 
justed to the left by the number 
of columns specified by the 
hscroll switch or less if in a 
small window. 


Moves the cursor to the left- 
most position in the window on 
the same line. 


Inserts one blank line above the 
current line. 


Inserts or deletes blanks at the 
beginning of a line to make the 
first nonblank character appear 
under the cursor. 


Fill the specified area with 
blanks. 


Moves the window to the 
beginning of the file. 


Restores the window to its pre- 
vious location. The editor re- 
members only the location 
prior to the last scrolling 
operation. 


Moves the cursor to the begin- 
ning of the line, where numarg 
specifies the position of the 
line in the file. 

Defines a file marker at the ini- 
tial cursor position. This does 
not record the file marker in the 
file specified by the markfile 
switch, but allows you to refer 
to this position as textarg. 
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Table A.3 (continued) 
Function (and 
Default Keystrokes) Syntax 
Arg streamarg Mark 
Arg textarg Mark 
Meta Meta 
(F9) 
Mlines Mlines 
(CTRL+W) 
Arg Mlines 
Arg numarg Mlines 
Mpage Mpage 
(PGUP or CTRL+R) 
Arg Mpage 
Arg numarg Mpage 
Mpara Mpara 
(CTRL+PGUP) 
Meta Mpara 
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Description 


Move the cursor to the 
specified file marker. If the file 
marker was not previously de- 
fined, the editor uses the mark- 
file switch to find the file that 
contains file marker defini- 
tions. For more information, 
see Section 7.4.3, “Text 
Switches.” 


Modifies the action of the func- 
tion it is used with. Refer to the 
individual functions for 
specific information. 


Moves the window back by the 
number of lines specified by 
the vscrol] switch or less if in a 
small window. 


Moves the window until the 
line that the cursor 1s on is at 
the bottom of the window. 


Moves the window back by the 
specified number of lines. 


Moves the window backward 
in the file by one window’s 
worth of lines. 


Moves the window to the 
beginning of the file. 


Moves the window the 
specified number of windows 
backward in the file. 


Moves the cursor to the first 
blank line preceding the current 
paragraph, or if currently on a 
blank line the cursor is posi- 
tioned before the previous 


paragraph. 
Moves cursor to the first pre- 
vious line that has text. 


Table A.3 (continued) 


Function (and 
Default Keystrokes) 


Msearch 
(F4) 


Mword 
(CTRL+LEFT 
or CTRL+A) 


Syntax 


Msearch 


Arg Msearch 


Arg streamarg Msearch 
Arg textarg Msearch 


Arg Arg Msearch 


Arg Arg streamarg Msearch 
Arg Arg textarg Msearch 


Mword 


Meta Mword 


Reference Tables 


Description 


Searches backward for the pre- 
viously defined string or pat- 
tern. If the string or pattern is 
found, the window is moved to 
display it and the matched 
string or pattern is highlighted. 
If no match is found, no cursor 
movement takes place and a 
message is displayed. 
Searches backward in the file 
for the string defined as the 
characters from the initial cur- 
sor position to the first blank 
character, 


Search backward for the 
specified text. 


Searches backward in the file 
for the regular expression de- 
fined as the characters from the 
initial cursor position to the 


| first blank character. 


Search backward for a regular 
expression as defined by 
streamarg or textarg. 


Moves the cursor to the begin- 
ning of a word. If not in a word 
or at the first character, use the 
previous word, otherwise use 
the current word. 


Moves the cursor to the imme- 
diate right of the previous 
word. 
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Table A.3 (continued) 

Function (and 

Default Keystrokes) Syntax. 

Newline Newline 
Meta Newline 

Paste Paste 

(SHIFT+INS) 
Arg Paste 
Arg streamarg Paste 
Arg textarg Paste 
Arg Arg streamarg Paste 
Arg Arg textarg Paste 


Arg Arg tstreamarg Paste 
Arg Arg ‘textarg Paste 
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Description 


Moves the cursor to a new line. 
If the softer switch is set, the 
editor tries to place the cursor 
in an appropriate position 
based on the type of file. If the 
file is a C program, the editor 
tries to tab in based on con- 
tinuation of lines and on open 
blocks. If the next line is blank, 
the editor places the cursor 

in the column corresponding to 
the first nonblank character of 
the previous line. If neither of 
the above is true, the editor 
places the cursor on the first 
nonblank character of the line. 


Moves the cursor to column 1 
of the next line. 


Inserts the contents of the Clip- 
board prior to the current line if 
the contents were placed there 
in a line-oriented way, such as 
with linearg or numarg. Other- 
wise the contents of the Clip- 
board are inserted at the current 
cursor position. 


Inserts the text from the initial 
cursor position to the end of the 
line at the initial cursor position. 


Place the specified text into the 
Clipboard and insert that text at 
the initial cursor position. 


Interpret textarg or streamarg 
as a file name and insert the 
contents of that file into the cur- 
rent file above the current line. 


Treat the text as a DOS com- 
mand and insert its output to 
stdout into the current file at 
the initial cursor position. The 
exclamation mark must be 
entered as shown. 


Table A.3 (continued) 
Function (and 
Default Keystrokes) Syntax 
Pbal Phal 
(CTRL+[) 
Arg Pbal 
Meta Pbal 
Arg Meta Pbal 
Plines Plines 
(CTRL+Z) 
Arg Plines 
Arg numarg Plines 
Ppage Ppage 
(PGDN or 
CTRL+C) 
Arg Ppage 
Arg numarg Ppage 


Reference Tables 


Description 


Scans backward through the 
file, balancing parentheses and 
brackets. The first unbalanced 
one is highlighted when found. 
If it is found and is not visible, 
the editor displays the match- 
ing line on the dialog line, with 
the highlighted matching 
character. The corresponding 
character is placed into the file 
at the current cursor position. 
Note that the search does not in- 
clude the current cursor posi- 
tion and that the scan only 
looks for more left brackets or 
parentheses than right, not just 
an unequal amount. 


Performs similarly to Pbal, ex- 
cept that it scans forward in the 
file and looks for more right 
brackets or parentheses than 
left. 


Performs similarly to Pbal, ex- 
cept that the file is not updated. 


Performs similarly to Arg Pbal, 
except that the file is not 
updated. 


Adjusts the window forward by 
the number of lines specified 
by the vscroll switch or less if 
in a small window. 


Moves the window downward 
so the line that the cursor is on 
is at the top of the window. 


Moves the window forward the 
specified number of lines. 


Moves the window forward in 
the file by one window’s worth 
of lines. 


Moves the window to the end 
of the file. 


Moves the window the 
specified number of windows 
forward in the file. 
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Table A.3 (continued) 
Function (and 
Default Keystrokes) Syntax 
Ppara Ppara 
(CTRL+PGDN) 
Meta Ppara 
Psearch Psearch 
(F3) 
Arg Psearch 
Arg streamarg Psearch 
Arg textarg Psearch 
Arg Arg Psearch 
Arg Arg streamarg Psearch 
Arg Arg textarge Psearch 
Pword Pword 
(CTRL+RIGHT 
or CTRL+F) 
Meta Pword 
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Description 


Moves the cursor forward one 
paragraph and places the cursor 
on the first line of the new 


paragraph. 

Moves the cursor to the first 
blank line following the current 
paragraph. 

Searches forward for the pre- 
viously defined string or pat- 
tern. If the string or pattern is 
found, the window is moved to 
display it and the matched 
string or pattern is highlighted. 
ff it is not found, no cursor 
movement takes place and a 
message is displayed. 


Searches forward in the file for 
the string defined as the 
characters from the initial cur- 
sor position to the first blank 
character. : 


Search forward for the 
specified text. 


Searches forward in the file for 
the regular expression defined 
as the characters from the ini- 
tial cursor position to the first 
blank character. 


Search forward for a regular 
expression as defined by 
streamarg or textarg. 


Moves the cursor forward one 
word and places the cursor on 
the beginning of the new word. 


Moves cursor to immediate 
right of current word, or if not 
in a word to the right of the 
next word. 


Reference Tables 


Table A.3 (continued) 


Function (and 
Default Keystrokes) Syntax Description 


Qreplace Qreplace | Performs a simple search-and- 

(CTRL+) replace operation, prompting 
you for the search and replace- 
ment strings, and prompting at 
each occurrence for confirma- 
tion. The search begins at the 
cursor position and continues 
through the end of the file. 


Arg boxarg Qreplace Perform the search-and-replace 

Arg linearg Qreplace operation over the specified 

Arg streamarg Qreplace text, prompting at each occur- 
rence for confirmation. 


Arg markarg Qreplace Performs the search-and- 
replace operation between 
the initial cursor position and 
the specified file marker, 
prompting at each occurrence 
for confirmation. 


Arg numarg Qreplace Performs the search-and- 
replace operation over the 
specified number of lines, 
starting with the current line, 
prompting at each occurrence 
for confirmation. 


Arg Arg Qreplace Perform the same as their re- 
Arg Arg boxarg Qreplace spective counterparts above, ex- 
Arg Arg linearg Qreplace cept that the search pattern is a 
Arg Arg markarg Qreplace regular expression and the re- 
Arg Arg numarg Qreplace placement pattern can select 
Arg Arg streamarg Qreplace special tagged sections of the 
search for selective replace- 
ment. See Chapter 5, “Regular 
Expressions,” for more 
information. 
Quote Quote Reads one keystroke from the 
(CTRL+P) keyboard and treats it literally. 
This is useful for inserting text 
into a file that happens to be as- 
signed to an editor function. 
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Table A.3 (continued) 

Function (and 

Default Keystrokes) Syntax 

Refresh Refresh 

(SHIFT+F7) 
Arg Refresh 

Replace Replace 

(CTRL+L) 
Arg boxarg Replace 
Arg linearg Replace 
Arg streamarg Replace 
Arg markarg Replace 
Arg numarg Replace 
Arg Arg Replace 
Arg Arg boxarg Replace 
Arg Arg linearg Replace 
Arg Arg markarg Replace 
Arg Arg numarg Replace 
Arg Arg streamarg Replace 

Restcur Restcur 
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Description 


Asks for confirmation and then 
rereads the file from disk, dis- 
carding all edits since the file 
was last saved. 


Asks for confirmation and then 
discards the file from memory, 
loading the last file edited in its 
place. 


Performs a simple search-and- 
replace operation without con- 
firmation, prompting you for 
the search string and replace- 
ment string. The search begins 
at the cursor position and con- 
tinues through the end of the 
file. 


Perform the search-and-replace 
operation over the specified 
text. 


Performs the search-and- 
replace operation between the 
cursor and the specified file 
marker. 


Performs the search-and- 
replace operation over the 
specified number of lines, 
starting with the current line. 


Perform the same as their re- 
spective counterparts above, ex- 
cept that the search pattern is a 
regular expression and the re- 
placement pattern can select 
special tagged sections of the 
search for selective replace- 
ment. See Chapter 5, ‘Regular 
Expressions,” for more 
information. 


Restores the cursor position 
saved with Savecur. 


Table A.3 (continued) 


Function (and 
Default Keystrokes) 


Right 
(RIGHT or 
CTRL+D) 


Savecur 


Sdelete 
(DEL) 


Setfile 
(F2) 


Syntax 
Right 


Meta Right 


Savecur 


Sdelete 


Arg Sdelete 


Arg boxarg Sdelete 
Arg linearg Sdelete 
Arg streamarg Sdelete 


Setfile 


Arg Setfile 


Arg streamarg Setfile 
Arg textarg Setfile 


Reference Tables 


Description 


Moves the cursor one character 
to the right. If this would result 
in the cursor moving out of the 
window, then the window is ad- 
justed to the right the number 
of columns specified by the 
hscroll switch or less if in a 
small window. 


Moves the cursor to the right- 
most position in the window. 


Saves the current cursor 
position to be restored with 
Restcur. 


Deletes the single character 
under the cursor, excluding 
line breaks. It does not place 
the deleted character into the 
Clipboard. 


Deletes from the cursor 
through the end of line, join- 
ing the following line with the 
current line at the point of the 
cursor position. The text de- 
leted (including the line break) 
is placed into the Clipboard. 


Delete the stream of text from 
the initial cursor position up to 
the current cursor position and 
place it into the Clipboard. 


Switches to the most recently 
edited file, saving any changes 
made to the current file to disk. 


Switches to the file name that 
begins at the initial cursor posi- 
tion and ends with the first 
blank. 


Switch to the file specified by 
streamarg or textarg. 
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Table A.3 (continued) 
Function (and 
Default Keystrokes) Syntax Description 
Meta Setfile Perform similarly to their coun- 
Arg Meta Setfile terparts above, but disable the 
Arg streamarg Meta Setfile saving of changes for the cur- 
Arg textarg Meta Setfile rent file. 
Arg Arg streamarg Setfile Save the current file under the 
Arg Arg textarg Setfile name specified by streamarg or 
fextarg. 
Arg Arg Setfile Saves the current file. 
Setwindow Setwindow Redisplays the entire screen. 
(CTRL+]) 
Meta Setwindow Redisplays the current line. 
Arg Setwindow Adjusts the window so that the 
initial cursor position becomes 
the home position (upper-left 
corner). 
Shell Shell Saves the current file and runs 
(SHIFT+F9) the command shell. 
| Meta Shell Runs the command shell 
without saving the current file. 
Arg Shell Uses the text on the screen 
from the cursor up to the end of 
line as a command to the shell. 
Arg boxarg Shell Treat each line of either argu- 
Arg linearg Shell ment as a separate command to 
the sheil 
Arg streamarg Shell Use streamarg or textarg as a 
Arg textarg Shell command to the shell. 
Sinsert Sinsert Inserts a single blank space at 
(CTRL+J) the current cursor position. 
Arg Sinsert Inserts a carriage return at the 
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Arg boxarg Sinsert 
Arg linearg Sinsert 
Arg streamarg Sinsert 


initial cursor position, splitting 
the line. 

Insert a stream of blanks be- 
tween the initial cursor position 
and the current cursor position. 


Table A.3 (continued) 


Function (and 
Default Keystrokes) 


Tab 
(TAB) 


Undo 
(ALT+BKSP) 


Window 
(F6) 


Syntax 
Tab 


Undo 


Up 


Meta Up 


Window 


Arg Window 


Arg Arg Window 


Meta Window 


Reference Tables 


Description 


Moves the cursor to the next 
tab stop. Tab stops are defined 
to be every mth character, 
where n is defined by the 
tabstops switch. 


Reverses the last editing 
change. The maximum number 
of times this can be performed 
is set by the undocount switch. 


Moves the cursor up one line. 
If this would result in the cur- 
sor moving out of the window, 
the window is adjusted upward 
by the number of lines 
specified by the yseroll switch 
or fewer if in a small window. 


Moves the cursor to the top of 
the window without changing 
the column position. 


Moves the cursor to the next 
window to the right of or below 
the current window. 


Splits the current window hori- 
zontally at the initial cursor 

position. Note that all windows 
must be at least five lines high. 


Splits the current window verti- 
cally at the initial cursor posi- 
tion. Note that all windows 
must be at least 10 columns 
wide. 


Closes the window. 
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Appendix B 


Support Programs 
for the Microsoft Editor 


This appendix discusses the following programs, which work in conjunction with the 
Microsoft Editor: 


e ECH.EXE 
© MEGREP.EXE 
¢ CALLTREE.EXE 


e¢ UNDEL.EXE, EXP.EXE, and RM.EXE 


The editor uses ECH.EXE in a way that is invisible to you; it is mentioned here only 
because it appears as a separate file on the disk. MEGREP.EXE searches through files 
for a string or regular expression. CALLTREE.EXE searches through program source 
files, locating function calls. The other three programs work with backup files. When a 
file is updated and the backup switch is set to undel, the old version of the file is 
copied to a hidden subdirectory called deleted. UNDEL.EXE, EXP.EXE, and 
RM.EXE manipulate the files in the deleted subdirectory. 


B.1 MEGREP.EXE 


Use this program to search through files for a simple string or regular expression. (See 
Chapter 5, “Regular Expressions,” for more information on regular expressions.) The 
following is the command-line syntax for MEGREP: 


megrep [/C] [[/c]] {/f patternfile | pattern} files 


MEGREP.EXE searches through files for pattern, where pattern may be a string or 
regular expression. The /C option makes case insignificant in the search. The /c option 
lists the number of matches that are made. The /f option specifies that pattern to search 
for is located in patternfile rather than on the command line. 
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Note 


MEGREP.EXE can be used separately or from within the Microsoft Editor using 
the Arg Arg textarg Compile command, where textarg uses the syntax described 
above. 


B.2, CALLTREE.EXE 


Use this program to create any of the following output files using C or assembly- 
language source files: 


® Calltree listing file 
* Called-by listing file 
® Warning listing file 
@ Marker file for the Microsoft Editor 
The following is the command-line syntax for CALLTREE: 


calltree [options] source-filename... 
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Table B.1 gives the options you can use with CALLTREE.EXE. 


Table B.1 

CALLTREE.EXE Options 

Option Meaning 

“a Causes the argument lists to be shown with procedure definitions 
and references in the calltree listing file. It also causes an entry in 
the warning listing file if there is a discrepancy in an argument list. 

-V Causes a complete (verbose) listing in the calltree listing file. A pre- 
viously viewed path is listed again, instead of being displayed as an 
ellipsis (...). 

-i Causes case insensitivity during name comparisons. 

-q | Prevents output from going to the screen (quiet mode). 

-s symbol Specifies to search only for symbol in the source files. 

-m filename Uses the symbols listed in filename for calltree information. 

-c filename Specifies the name of the calltree listing file. 

-b filename Specifies the name of the called-by listing file. 

-w filename Specifies the name of the warning listing file. 

-Z filename Specifies the name of the marker file that is created for use with the 
Microsoft Editor. 

source-filename... Specifies the names of the source files to use. The use of wildcards 


is permitted. 
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The calltree listing file produces an indented listing showing the procedure names at 
the left margin. Calls are shown indented four spaces per level. If a path has already 
been viewed, it is shown as an ellipsis (...). A recursive call is shown as an asterisk (*). 
If a call for an undefined procedure is made, a question mark (?) appears. 


The called-by listing file produces a tabled listing of defined procedures and all refer- 
ences to them. The procedure names are sorted alphabetically. 


The warning listing file lists duplicate procedure names and argument-list discrepan- 
cies if the -a and -b options are used. 


The Microsoft Editor marker file lists the name, the file it was found in, and the line 
and column numbers for each function. This allows you to move quickly to any func- 
tion, using the Arg markarg Mark command, by entering the function name as 
markarg. Use the markfile switch to provide the Microsoft Editor with the name of 
this file. 


B.3. UNDEL.EXE 


Use this program to move a file from the DELETED subdirectory to the parent 
directory. Its command-line syntax is as follows: 


undel [filename] 


If filename is not given, the contents of the DELETED subdirectory are listed. If there 
is more than one version of the file, you are given a list to choose from. If the file al- 
ready exists in the parent directory, the two files are swapped. 
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B.4 EXP.EXE 


Use this program to remove all of the files in the specified directory’s hidden 
DELETED subdirectory. Use the following command-line syntax: 


exp [/r] [/qD]] [directory] 


If no directory is specified, then the current directory’s DELETED subdirectory is 
used. If the /r option is given, EXP.EXE recursively operates on all subdirectories. 
The /q option specifies quiet mode; the deleted file names are not displayed on the 
screen. 


B.5 RM.EXE 


Use this program to move one or more files from its current directory into the 
DELETED subdirectory. The following is the command-line syntax for RM: 


rm [[/i] [/r] [/f] filename... 


The /i option prompts you for confirmation for each file it is about to delete. The /r op- 
tion causes RM.EXE to recursively operate on all subdirectories. The /f option forces 
read-only files to be deleted without prompting. 
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Glossary 


This glossary defines terms that this manual uses in a technical or unique way. 


Arg 


A function modifier that introduces an argument or an editing function. The argu- 
ment may be of any type and is passed to the next function as input. For example, 
the command Arg textarg Copy passes the argument textarg to the function Copy. 


argument 


An input to a function. The Microsoft Editor uses two classes of arguments: cursor- 
movement arguments and text arguments. Cursor-movement arguments (boxarg, 
linearg, and streamarg) specify a range of characters on the screen. Text argu- 
ments (markarg, numarg, and textarg) allow you to enter information to be used 
by a function. Arguments are introduced by using the Arg function. 

assignment 


See “function assignment.” 


boxarg 


A rectangular area on the screen, defined by the two opposite corners: the initial 
cursor position and the current cursor position. The two cursor positions must be 
on separate rows and separate columns. A boxarg is generated by invoking the Arg 
function and then moving the cursor to a new location. 


buffer 
An area in memory in which a copy of the file is kept and changed as you edit. 
This buffer is copied to disk when you do a save operation. 

C extension 
A C-language module that defines new editing functions and switches. 


See Chapter 8, “Programming C Extensions.” 


Clipboard 


A section of memory that holds text that has been deleted with the Copy, Ldelete, 
or Sdelete functions. You can use the Paste function to insert text from the Clip- 
board into a file. 
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configuration 


A description of the specific assignments of functions to keys. For example, a 
BRIEF configuration implies that the Microsoft Editor uses keys similar to those 
that the BRIEF editor uses to invoke similar functions. 
default 
A setting that is assumed by the editor until you specify otherwise. The Microsoft 
Editor uses two categories of default settings: function assignments and switches. 
emacs 


A popular type of editor, from which the functions Emacscdel and Emacsnewl 
were taken. 


function assignment 


A method of assigning an editor function to a specific keystroke so that pressing 
the keystroke invokes the function. Use the Arg textarg Assign command to make 
an assignment for a single editing session, or you can enter the assignment in the 
TOOLS.INI file so that it may be used during any editing session. 


See Chapter 6, “Function Assignments and Macros.” 


initial cursor position 


The position the cursor is in when the Arg function is invoked. 


insert mode 
An input mode that inserts rather than replaces characters in the file as they are 
entered. 

linearg 


A range of complete lines, including ail the lines from the initial cursor position to 
the current cursor position. You define a linearg by invoking the Arg function 
(pressing ALT+A), then moving the cursor to a different line but same column as 
the initial cursor position. 


macro 


A function that is made up of arguments and previously defined functions. For ex- 
ample, you can create a macro that contains a set of functions that you perform re- 
peatedly and assign the macro to a keystroke. Those functions can now be carried 
out much more quickly and simply by invoking the macro. 


See Chapter 6, “Function Assignments and Macros.” 
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markarg 
A special type of textarg that has been previously defined to be a marker, that is, it 
is associated with a particular position in the file. 

marker 


A name assigned to a cursor position in a file so that this position can be referred 
to within a command by using this name. For example, you could perform the 
command Arg markarg Mark to move to the marker specified by markarg. A 
marker is assigned using the Arg Arg textarg Mark command. 

Meta 
A function that modifies other functions so they perform differently, similar to the 
way CTRL or ALT modifies a key so that it performs differently. 

numarg 


A numerical value you enter on the dialog line, which is passed to a function. A nu- 
-marg is introduced by the Arg function. 


regular expression 


A pattern for specifying a set of strings of characters to search for. It may be a 
simple string or a more complex arrangement of characters and special symbols 
that specify a variety of strings to be matched. 


See Chapter 5, “Regular Expressions.” 


return value 


A value returned by an editing function. The value may be true or false, depending 
on whether the function was successful. This value can be used to create complex 
macros that perform differently depending upon the results of individual functions 
within the macro. 


See Chapter 6, “Function Assignments and Macros.” 


Sfreamarg 


A highlighted continuous string of characters on a single line. A streamarg is 
specified by invoking the Arg function and moving the cursor to any other posi- 
tion on the same line. 


switch 


A variable that modifies the way the editor performs. The Microsoft Editor uses 
three kinds of switches: Boolean switches, which turn a certain editor feature on 
or off; numeric switches, which specify numeric constants; and text switches, 
which specify a string of characters. | 


See Chapter 7, “Using the TOOLS.INI File.” 
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textarg 


A string of text that you enter on the dialog line, after invoking the Arg function 
(by pressing ALT+A). The text that you enter is passed as input to the next function. 


TOOLS.INI 


A file that contains initialization information for the Microsoft Editor and other 
programs. The file is divided into sections with the use of tags, and these sections 
can be loaded automatically when the editor is started or by command from within 
the editor. 


See Chapter 7, “Using the TOOLS.INI File.” 


window 


An area on the screen used to display part of a file. Unless a file is extremely 
small, it is impossible to see all of it on the screen at once. Therefore you see a por- 
tion of the file through the main editing window at any one time, and it is possible 
to see any part of the file by moving or scrolling this window. The Microsoft Edi- 
tor allows you to open multiple windows on the screen, using the Window func- 
tion, for viewing different parts of the same file or different files. 
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Index 


Argument types, 18 
Argument, defined, 117 
Arrow keys, 4 
Assignment, defined, 117 


Boolean switches, 60 


boxarg, argument type, 24, 117 


Buffer, defined, 117 


C extensions 
compiling and linking, 83 
defined, 1, 117 
functions, declaring, 70, 72 
functions, low level, 77 
loading, 69, 84 
programming, 67 
switches, declaring, 70 - 71 
types, function, 72 
CALLTREE.EXE file, 112 
Clipboard, defined, 117 
Colors, setting, 58 
Command line, 12 
Commands 
defined, 15 
entering, 16 
Comments, 55 
Compiling, 35 
Configuration, defined, 118 
Copying text, 29 


Cursor, initial position, 21, 118 
Cursor-movement arguments, 21 


Default, defined, 118 
Deleting text, 8, 28 
Direction keys, 4 


ECH.EXE file, 111 

Editing 
copying text, 29 
deleting text, 8, 28 
exiting, 12 
insert mode, 118 
inserting text, 8, 28 
moving text, 10, 29 
moving, through a file, 25 
overtype mode, 7 


replacing text, 7, 32 
scrolling, 26 

search and replace, 32 
starting editor, 6 


Emacs, defined, 118 
Error output, viewing, 36 


Exiting, from the editor, 12 
EXP.EXE file, 115 
Expressions 

predefined regular, 44 

regular, 39, 119 

tagged, 43 


File markers, in commands, 31 
Files 
CALLTREE.EXE, 112 
ECH.EXE, 111 
EXP.EXE, 115 
loading, 13 
M.EXE, 6 
MEGREP.EXE, 111 
MESETUP.BAT, 45 
multiple, 38 
RM.EXE, 115 
TOOLS .INI, 55 
UNDEL.EXE, 114 
Function assignments 
defined, 118 
graphic, 48 
keys, numeric keypad, 4, 47 
making, 46, 56 
removing, 47 
viewing, 47 
Functions 
Arg, 8, 93, 117 
Argcompile, 93 
Assign, 93 
Backtab, 93 
Begline, 93 
Cancel, 9, 93 
Cdelete, 94 
Compile, 35, 94 
Copy, 29, 95 
Curdate, 30, 95 
Curday, 30, 96 
Curfile, 30, 96 
Curfileext, 30, 96 
Curfilenam, 30, 96 
Curtime, 30, 96 
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Curuser, 30, 96 
Down, 26, 96 
Emacscdel, 96 
Emacsnewl, 96 
Endline, 96 
Execute, 97 

Exit, 12, 97 
Graphic, 48 

Help, 12, 97 
Home, 97 
Information, 38, 97 
Initialize, 98 
Insertmode, 8, 98 
Lasttext, 98 
Ldelete, 10, 28, 98 
Left, 26, 99 
Linsert, 28, 99 
Mark, 31, 99 
Meta, 17, 100, 119 
Mlines, 100 
Mpage, 26, 100 
Mpara, 100 
Msearch, 33, 101 
Mword, 27, 101 
Newline, 102 
Paste, 11, 29, 102 
Pbal, 103 

Plines, 103 
Ppage, 26, 103 
Ppara, 104 
Psearch, 11, 32, 104 
Pword, 27, 104 
Qreplace, 34, 105 
Quote, 105 
Refresh, 106 
Replace, 34, 106 
Restcur, 32, 106 
Right, 26 
Savecur, 32, 107 
Sdelete, 8, 28, 107 
Setfile, 12, 38, 107 
Setwindow, 108 
Shell, 108 

Sinsert, 108 

Tab, 109 
Unassigned, 47 
Undo, 9, 109 

Up, 26, 109 
Window, 37, 109 


Highlighting, 21 
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Initial cursor position, 21, 118 
Insert mode, defined, 118 
Inserting text, 8, 28 


Keys, numeric keypad, 4, 47 
Keystrokes, default, 90 


linearg, argument type, 23, 118 
Loading a file, 13 


M.EXE file, 6 
Macros 

assigning, to keys, 50 

defined, 118 

entering, 49, 56 

using conditionals with, 50 
markarg, argument type, 20, 119 
Markers, defined, 119 
Matching 

maximal, 42 

minimal, 42 
Matching method, 42 
MEGREP.EXE file, 111 
MEP.EXE file, 6 
MESETUP.BAT file, 45 
Moving text, 10, 29 
Moving, through a file, 25 
Multiple files, 38 


numarg, argument type, 19, 119 
Numeric switches, 57 
Numeric-keypad keys, 4, 47 


Overtype mode, 7 


Predefined regular expressions, 44 


Reading, from a file, 30 
Regular expressions, 39, 119 
Replacing text 

overtype mode, 7 

search and replace, 32 
Return value, defined, 119 
RM.EXE file, 115 


Scrolling 
horizontal, 26 
vertical, 26 | 

Search and replace, 32 

Setup program, 45 

Starting the editor, 6 

streamarg, argument type, 22, 119 

Switches © 
askexit, 61 
askrtn, 61 
autosave, 61 
backup, 62 
Boolean, 60 
case, 61 
defined, 119 
displaycursor, 61 
entab, 59 
enterinsmode, 61 
errcolor, 59 
extmake, 62 
fgcolor, 59 
height, 59 
hgcolor, 59 
hike, 59 
hscroll, 59 
infcolor, 59 
load, 62 
markfile, 63 
maxmsg, 59 
noise, 59 
numeric, 57 
readonly, 63 
rmargin, 60 
savescreen, 61 
setting, 57 
shortnames, 61 
softcr, 61 
stacolor, 60 
tabdisp, 60 
tabstops, 60 
text, 62 
tmpsav, 60 
traildisp, 60 
trailspace, 61 
undocount, 60 
vmbuf, 60 
vscroll, 60 
width, 60 
wordwrap, 61 

Syntax, command, 16 

System requirements, 2 
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Tagged expressions, 43 

Tags, 63 

Text arguments, 18 

Text switches, 62 

textarg, argument type, 21, 120 
TOOLS INI file, 55, 120 
Typographical conventions, 3 


UNDEL.EXE file, 114 


Window, defined, 120 
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